@jini-ai/agent-plugins 0.4.0 → 0.4.2

package/dist/lifecycle/bundled-digests.js

@@ -1,3 +1,65 @@
+/**
+ * @file The per-workspace ledger of WHICH installed digest each bundled Agent Plugin currently
+ * ships as — written by `seed-bundled.ts` on every boot, read by the surfaces that have to pick one
+ * installed package for a plugin id.
+ *
+ * ---------------------------------------------------------------------------
+ * The gap this closes
+ * ---------------------------------------------------------------------------
+ * `packages/sha256/<digest>/` is content-addressed and nothing retires an entry, so shipping a NEW
+ * VERSION of an already-installed bundled plugin lands it ALONGSIDE the old one. Both consumption
+ * surfaces then refuse that plugin outright as ambiguous — `resolve-agent-plugin-refs.ts`'s
+ * "refusing to guess which one to use" and `tool-registrations.ts`'s `poisonedPluginIds`. A product
+ * upgrade therefore broke every enabled bundled plugin whose bytes it touched, silently, on the next
+ * boot. Observed live: `higgsfield-media` (2 digests, enabled, tools gone), `supabase` (3 digests,
+ * dormant), and `github` one boot away from the same fate.
+ *
+ * ---------------------------------------------------------------------------
+ * Why a ledger rather than deleting, or than "prefer the newest"
+ * ---------------------------------------------------------------------------
+ * The ambiguity refusal itself is deliberate and stays exactly as it was — `resolve-agent-plugin-
+ * refs.ts`'s header argues at length that silently picking one (the lexicographically-last, the
+ * newest mtime, whatever hashed later) would be a WORSE failure mode than an explicit error, because
+ * a wrong plugin's content would reach the agent and nothing about the run would look wrong. That
+ * reasoning is untouched here. What changes is that for a BUNDLED plugin there is now something
+ * authoritative to consult instead of guessing: the build's own seed recorded which digest it
+ * published. A digest wins because the host shipped it, never because it sorted first.
+ *
+ * Three consequences worth stating plainly, because each one is a refusal this file deliberately
+ * keeps:
+ *
+ * 1. **An id with no ledger entry is still ambiguous.** Two digests of a plugin the seeder never
+ *    seeded — an operator's own installs — remain an explicit error. Nothing here has any authority
+ *    over a package the host did not put on disk.
+ * 2. **A ledger entry that names a digest which is not installed decides nothing.** The named digest
+ *    has to be present, and be exactly one of the candidates, or the ambiguity stands.
+ * 3. **An unreadable ledger reads as an empty one.** That is fail-CLOSED here, unlike
+ *    `activation.ts`'s own lenient reader: an empty ledger names no winner, so every ambiguity stays
+ *    an error. This file can only ever resolve an ambiguity, never create one.
+ *
+ * ---------------------------------------------------------------------------
+ * Nothing is deleted, moved, or renamed
+ * ---------------------------------------------------------------------------
+ * A superseded digest's bytes stay exactly where they are. Retiring by moving directories out of a
+ * live `packages/sha256/` at boot was the other candidate design and was rejected: it mutates the
+ * operator's package store on a code path whose whole job is supposed to be idempotent, it races
+ * anything mid-read, and — since a digest's provenance is NOT recorded per-digest anywhere — a
+ * workspace that already held an operator's own install under a bundled plugin's id could have had
+ * that operator's bytes moved aside by an inference. Preferring a digest at READ time disturbs
+ * nothing and is undone by deleting one small JSON file. The cost is disk: superseded packages
+ * accumulate until an operator prunes them, which is their call to make and reversible either way.
+ *
+ * Architectural role:
+ * Owns one small JSON file and one pure selection rule. No knowledge of activation, installation, or
+ * tools — `seed-bundled.ts` is the only writer (plus `retire-bundled.ts`, which it calls in the same
+ * boot step), and the read side is two call sites that already
+ * hold both a workspace root and a list of installed packages.
+ */
+/** Where a workspace's bundled-digest ledger lives, beside `activation.ts`'s `activations.json` and
+ *  for the same reason: it is a fact about this workspace, not about a package. */
+/** The same 64-lowercase-hex shape `resolve-agent-plugin-refs.ts` requires of an installed package
+ *  directory name. A ledger entry that does not match it could never name a real install. */
+/** The Agent Plugins name grammar, as `activation.ts` and `layout.ts` both already enforce it. */
 /** Extracted from the host plugin lifecycle. Effects are supplied per host context. */
 import path from "node:path";
 export const BUNDLED_DIGESTS_FILENAME = "bundled-digests.json";
@@ -10,6 +72,17 @@ function buildModule(ports) {
     const SHA256_DIGEST_PATTERN = /^[a-f0-9]{64}$/;
     const SAFE_PLUGIN_ID_PATTERN = /^[a-z0-9]+(?:[-.][a-z0-9]+)*$/;
     const EMPTY_LEDGER = new Map();
+    /**
+   * Reads one workspace's bundled-digest ledger.
+   *
+   * @param workspaceRoot - `AgentPluginWorkspaceLayout.root`, never an instance-level path.
+   * @returns The recorded plugin-id -> digest map, or an EMPTY map for a missing, unreadable,
+   * malformed, or wrong-version file. Malformed INDIVIDUAL entries are skipped rather than discarding
+   * the whole ledger, matching `activation.ts`'s own per-entry discipline.
+   * @throws Nothing. An empty answer is always safe: it names no winner, so every ambiguity this
+   * module could have resolved simply stays the explicit error it already was.
+   * @complexity One file read plus O(p) in the recorded plugin count.
+   */
     async function readBundledAgentPluginDigests(workspaceRoot) {
         let raw;
         try {
@@ -27,6 +100,12 @@ function buildModule(ports) {
         }
         return normalizeBundledDigests(parsed);
     }
+    /**
+   * Validates an already-`JSON.parse`d ledger value, dropping anything that does not match the shape.
+   * Pure, so the parsing rules are assertable without touching a filesystem.
+   *
+   * @complexity O(p) in the entry count.
+   */
     function normalizeBundledDigests(value) {
         if (!isPlainObject(value) || value.schemaVersion !== 1 || !isPlainObject(value.plugins))
             return EMPTY_LEDGER;
@@ -43,6 +122,27 @@ function buildModule(ports) {
         }
         return digests;
     }
+    /**
+   * Records the digest this boot seeded for each bundled plugin, merged over whatever was already
+   * recorded.
+   *
+   * MERGED, not replaced, for failure isolation (the property `seed-bundled.ts`'s header names): a
+   * plugin that failed to seed this boot — an unreadable source directory, a transient I/O fault —
+   * must not lose the perfectly good entry an earlier boot wrote for it, which is what a wholesale
+   * rewrite of only this boot's successes would do.
+   *
+   * A plugin id seeded TWICE in one run under two different digests (two bundled source directories
+   * declaring the same manifest `name`) is dropped from the ledger entirely, prior entry included:
+   * the build itself is ambiguous about what it ships, so there is nothing authoritative to record and
+   * the explicit ambiguity refusal downstream is the correct outcome.
+   *
+   * @param seeded - One entry per successfully seeded plugin. An empty list writes nothing at all —
+   * not even an empty file — so a boot that seeded nothing cannot create a workspace directory or
+   * truncate an existing ledger.
+   * @throws {Error} Any filesystem fault from the write. The caller (`seed-bundled.ts`) captures it
+   * into its report rather than failing the boot.
+   * @complexity One file read and one atomic write, O(p) in the recorded plugin count.
+   */
     async function recordBundledAgentPluginDigests(required) {
         if (required.seeded.length === 0)
             return;
@@ -58,6 +158,15 @@ function buildModule(ports) {
         const plugins = Object.fromEntries([...merged].map(([pluginId, archiveDigest]) => [pluginId, { archiveDigest, seededAt }]));
         await writeLedgerAtomically(required.workspaceRoot, plugins);
     }
+    /**
+   * This boot's verdict per plugin id: the digest it seeded, or `undefined` when the run seeded the
+   * same id under two different digests and therefore has no authoritative answer for it.
+   *
+   * Split out as a pure step so the "a self-contradictory build records NOTHING" rule is assertable
+   * without a filesystem, and so {@link recordBundledAgentPluginDigests} reads as merge-then-write.
+   *
+   * @complexity O(n) in the seeded-entry count.
+   */
     function resolveThisBootsDigests(seeded) {
         const thisBoot = new Map();
         for (const { pluginId, archiveDigest } of seeded) {
@@ -70,6 +179,19 @@ function buildModule(ports) {
         }
         return thisBoot;
     }
+    /**
+   * Drops one plugin id from the ledger — for `retire-bundled.ts`, once a retired bundled plugin's
+   * packages are gone and no build will ever seed it again.
+   *
+   * Every other entry is kept byte-for-byte, `seededAt` included: this rewrites the raw `plugins` bag
+   * rather than the normalized map, so it cannot lose a field a later schema adds. A missing,
+   * unreadable, malformed, or wrong-version ledger, or one with no entry for `pluginId`, writes
+   * nothing — there is nothing to drop, and a fail-closed reader already treats such a file as empty.
+   *
+   * @returns Whether an entry was removed.
+   * @throws {Error} Any filesystem fault from the write. `retire-bundled.ts` captures it into its report.
+   * @complexity One file read and at most one atomic write, O(p) in the recorded plugin count.
+   */
     async function removeBundledAgentPluginDigest(required) {
         let parsed;
         try {
@@ -87,6 +209,11 @@ function buildModule(ports) {
         await writeLedgerAtomically(required.workspaceRoot, remaining);
         return true;
     }
+    /** Temp-file-then-`rename`, so a reader never observes a half-written ledger and a crash mid-write
+   *  leaves the previous one intact — the same durability shape `activation.ts`'s
+   *  `writeActivationsAtomically` uses, minus its cross-process lock: this file has exactly one writer
+   *  (the boot seeder, retirement included), and two concurrent boots of the SAME build write byte-identical content.
+   *  @complexity One write and one rename. */
     async function writeLedgerAtomically(workspaceRoot, plugins) {
         const finalPath = path.join(workspaceRoot, BUNDLED_DIGESTS_FILENAME);
         const tempPath = `${finalPath}.tmp-${ports.process.pid}-${randomUUID()}`;
@@ -106,6 +233,24 @@ function buildModule(ports) {
             throw error;
         }
     }
+    /**
+   * Drops the SUPERSEDED installs of any bundled plugin id from a list of installed packages, leaving
+   * every other entry — and every other plugin id — exactly as it was.
+   *
+   * An id is narrowed only when all three hold: it has more than one installed digest, the ledger
+   * records a digest for it, and exactly one of its installed digests is that recorded one. Anything
+   * else passes through untouched, so the caller's own ambiguity refusal still fires for every case
+   * this module has no authority over (this file's header, consequences 1 and 2).
+   *
+   * Applied at READ time by the surfaces that must pick one package per plugin id. Deliberately NOT
+   * folded into `listInstalledPlugins` itself: `uninstall.ts` needs to see EVERY digest of a plugin to
+   * remove them, and a filter hidden inside the shared walk would make superseded bytes unremovable.
+   *
+   * @returns A list in the input's own order, with superseded entries removed. The input is never
+   * mutated.
+   * @complexity O(n) in the installed-package count, over one O(n) pre-pass that counts digests per
+   * plugin id.
+   */
     function preferBundledAgentPluginDigests(installed, bundled) {
         if (bundled.size === 0)
             return installed;
@@ -114,6 +259,12 @@ function buildModule(ports) {
             return installed;
         return installed.filter((plugin) => !supersededIds.has(plugin.pluginId) || plugin.archiveDigest === bundled.get(plugin.pluginId));
     }
+    /**
+   * The plugin ids whose installed digests the ledger can authoritatively narrow to one — every id
+   * that is installed under several digests, exactly one of which is the digest this build seeded.
+   *
+   * @complexity O(n) in the installed-package count.
+   */
     function idsNarrowableToTheirBundledDigest(installed, bundled) {
         const digestsByPluginId = new Map();
         for (const plugin of installed) {
@@ -131,6 +282,11 @@ function buildModule(ports) {
         }
         return narrowable;
     }
+    /** Whether `value` is a plain (non-null, non-array) object — the shape both this file's JSON-adjacent
+   *  values must have before their own fields are worth looking at. Duplicated from `activation.ts`'s
+   *  private helper of the same name rather than widening that module's public surface, matching this
+   *  codebase's own precedent for small private formatting/shape helpers (see `resolve-agent-plugin-
+   *  refs.ts`'s note on `humanize()`). */
     function isPlainObject(value) {
         return typeof value === "object" && value !== null && !Array.isArray(value);
     }

package/dist/lifecycle/bundled-source-archive.d.ts

@@ -2,7 +2,10 @@ import type { AgentPluginArchiveReaderPort } from "./install.js";
 import type { AgentPluginLifecyclePorts } from "./ports.js";
 export interface PackedAgentPluginArchive {
     readonly bytes: Uint8Array;
+    /** Lowercase hex SHA-256 of {@link bytes} — passed straight to `installAgentPlugin`'s
+     *  `expectedSha256`, which recomputes and compares it rather than trusting it. */
     readonly sha256: string;
+    /** Package-relative POSIX paths included, sorted — the same order they appear in `bytes`. */
     readonly files: readonly string[];
 }
 /** Internal composition; one state/queue instance per injected host context. */

package/dist/lifecycle/bundled-source-archive.js

@@ -1,3 +1,45 @@
+/**
+ * @file Turns a bundled Agent Plugin's SOURCE DIRECTORY (tracked in this repo, shipped in the
+ * product) into the `{ archive: Uint8Array, expectedSha256, archiveReader }` triple
+ * `installAgentPlugin` requires — so a pre-placed package goes through the exact same install path
+ * as one downloaded from a URL, rather than around it.
+ *
+ * ---------------------------------------------------------------------------
+ * Why not just copy the directory
+ * ---------------------------------------------------------------------------
+ * Because `installAgentPlugin` is where every guarantee lives: lexical and symlink zip-slip
+ * refusal, entry/file/total-byte caps, atomic staging-then-publish, `chmod 0o555` freezing,
+ * content-addressed dedup, and the tenant-scoped `forWorkspace()` resolution that makes it
+ * impossible to publish into another workspace's tree. A `cp -R` in a seeder would reimplement
+ * none of them, and every one it skipped would be a guarantee that silently applies to
+ * operator-installed plugins and not to the one the host ships itself.
+ *
+ * The obstacle is only that `installAgentPlugin` speaks archives, and a directory is not one.
+ * {@link packAgentPluginDirectory} therefore serialises the directory into a tiny, deterministic
+ * archive format, and {@link createBundledSourceArchiveReader} reads it back — a round trip, not a
+ * bypass. `yauzl`/`yazl` were the obvious alternative and are wrong here: `yazl` is a
+ * devDependency used only by dev tooling and test fixtures (`development/scripts/package-agent-plugin.ts`
+ * says so in its own header, "must never be imported by production code"), and DEFLATE would make
+ * the digest depend on a compressor's version rather than on the bytes.
+ *
+ * ---------------------------------------------------------------------------
+ * The digest is a real content digest
+ * ---------------------------------------------------------------------------
+ * `installAgentPlugin` verifies `sha256(archive) === expectedSha256` before extracting anything, and
+ * uses that digest as the content address. Because this format is byte-deterministic — sorted
+ * paths, explicit lengths, no timestamps, no permissions, no compression — the digest is a genuine
+ * function of the package's own file contents and names. Two builds of the same source tree produce
+ * the same digest, which is what makes seeding idempotent (`install.ts`'s `alreadyPublished` fast
+ * path) instead of re-extracting on every boot.
+ *
+ * Architectural role:
+ * One directory walk (the only I/O) plus a pure encoder/decoder pair. `seed-bundled.ts` composes it
+ * with `installAgentPlugin`.
+ */
+/** Magic + version line. A reader that does not see this refuses rather than guessing. */
+/** Guards a caller that points this at the wrong directory (a `node_modules`, a whole repo). Well
+ *  above any real plugin; below `install.ts`'s own `maxEntries` of 4096 so the friendlier error
+ *  comes from here. */
 /** Extracted from the host plugin lifecycle. Effects are supplied per host context. */
 import { createHash } from "node:crypto";
 import path from "node:path";
@@ -6,6 +48,20 @@ function buildModule(ports) {
     const readFile = ports.filesystem.readFile.bind(ports.filesystem);
     const MAGIC = ports.bundledArchiveMagic;
     const MAX_SOURCE_FILES = 2048;
+    /**
+   * Serialises every regular file under `sourceDir` into one deterministic archive.
+   *
+   * Symlinks and any other non-regular entry are skipped rather than followed: a bundled package is
+   * this repository's own tracked content, so a symlink in it would be a mistake, and following one
+   * is the exact vector `install.ts` refuses on the extraction side. Skipping keeps the two sides
+   * agreeing instead of producing an archive the installer would then reject.
+   *
+   * @throws {Error} If the tree holds more than {@link MAX_SOURCE_FILES} files.
+   * @throws Propagates `readdir`/`readFile` errors — a bundled package that cannot be read is a build
+   * defect, not a runtime condition to degrade around.
+   * @complexity O(f) files, O(b) total bytes; both bounded by the cap above and by `install.ts`'s own
+   * `LIMITS` on the extraction side.
+   */
     async function packAgentPluginDirectory(sourceDir) {
         const relativePaths = (await listRegularFiles(sourceDir, "")).sort();
         if (relativePaths.length > MAX_SOURCE_FILES) {
@@ -24,6 +80,16 @@ function buildModule(ports) {
             files: relativePaths,
         };
     }
+    /**
+   * Reads the format {@link packAgentPluginDirectory} writes, as an `AgentPluginArchiveReaderPort`.
+   *
+   * Yields only `kind: "file"` entries — the format has no directory, symlink, or device entries to
+   * represent, which is itself a small safety property: the whole class of entry `install.ts` rejects
+   * cannot be expressed in an archive this reader produces.
+   *
+   * @complexity O(n) in the archive's byte length; each file's bytes are yielded once, not copied
+   * into an intermediate list.
+   */
     function createBundledSourceArchiveReader() {
         return {
             entries({ archive }) {
@@ -64,9 +130,16 @@ function buildModule(ports) {
             offset = contentEnd;
         }
     }
+    /** One-shot async iterable over a single chunk — the shape `AgentPluginArchiveEntry.openReadStream`
+   *  wants, without pulling in a stream implementation for an already-in-memory buffer. */
     async function* onceAsyncIterable(chunk) {
         yield chunk;
     }
+    /**
+   * Lists every regular file under `dir`, as POSIX-style package-relative paths.
+   *
+   * @complexity O(f) in filesystem entries under `dir`.
+   */
     async function listRegularFiles(dir, prefix) {
         const entries = await readdir(dir, { withFileTypes: true });
         const files = [];
@@ -78,6 +151,7 @@ function buildModule(ports) {
             else if (entry.isFile()) {
                 files.push(relative);
             }
+            // Symlinks and everything else: skipped. See this function's own doc.
         }
         return files;
     }

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

@@ -0,0 +1,102 @@
+import type { TrustedPluginPackage, TrustedPluginPackagesQuery, TrustedPluginVerdict } from './trusted-plugin-files.js';
+export type PluginContributionParseResult<T> = {
+    readonly ok: true;
+    readonly descriptors: readonly T[];
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+export interface PluginContributionResult<T> {
+    readonly items: readonly T[];
+    readonly refusals: readonly string[];
+}
+export type PluginModuleImportPort = (input: {
+    readonly plugin: TrustedPluginPackage;
+    readonly modulePath: string;
+}) => Promise<{
+    readonly exported: unknown;
+} | string>;
+export interface PluginContributionDefinition<D, T> {
+    readonly filename: string;
+    readonly contribution: string;
+    readonly kind: 'data' | 'executable';
+    readonly parse: (input: {
+        readonly raw: string;
+    }) => PluginContributionParseResult<D>;
+    /** A string is the complete refusal line; successful values retain declaration order. */
+    readonly load: (input: {
+        readonly plugin: TrustedPluginPackage;
+        readonly descriptor: D;
+        readonly importModule: PluginModuleImportPort;
+    }) => T | string | Promise<T | string>;
+    /** Undefined propagates the fault; [] deliberately tolerates a missing source manifest. */
+    readonly onReadError?: (input: {
+        readonly plugin: TrustedPluginPackage;
+        readonly error: unknown;
+    }) => readonly string[] | undefined;
+}
+export interface LoadedPluginContribution<D, M> {
+    readonly descriptor: D;
+    readonly pluginId: string;
+    readonly module: M;
+}
+export interface PluginContributionPorts {
+    readonly findPackages: (input: TrustedPluginPackagesQuery) => Promise<readonly TrustedPluginVerdict[]>;
+    readonly readFile: (input: {
+        readonly plugin: TrustedPluginPackage;
+        readonly filename: string;
+    }) => Promise<string>;
+    readonly importModule: PluginModuleImportPort;
+}
+export interface LoadPluginContributionsOptional {
+    /** Executable definitions always require activation, even if this option is false. */
+    readonly requireActive?: boolean;
+    readonly orderByPluginId?: boolean;
+    readonly onInactive?: TrustedPluginPackagesQuery['onInactive'];
+    readonly packageRefusal?: (input: {
+        readonly plugin: TrustedPluginPackage;
+    }) => string | undefined;
+}
+/** Bind traversal to the lifecycle's existing trust/read/import owner. Parser and error policies
+ * remain contribution ports: manifests and refusal contracts do not change.
+ * @param required - Trusted-file effects, injectable for direct failure and ordering tests.
+ * @returns Installed and explicitly trusted source loaders; reads are fresh on each call.
+ * @complexity O(p + d) packages and declarations, plus their file/import I/O; O(d + r) output space.
+ */
+export declare function createPluginContributionLoader(required: PluginContributionPorts, _optional?: Record<string, never>): {
+    loadPluginContributions: <D, T>(input: {
+        readonly workspaceId: string;
+        readonly definition: PluginContributionDefinition<D, T>;
+    }, options?: LoadPluginContributionsOptional) => Promise<PluginContributionResult<T>>;
+    loadPluginContributionsFromSource: <D, T>(input: {
+        readonly plugin: TrustedPluginPackage;
+        readonly definition: PluginContributionDefinition<D, T>;
+    }, _options?: Record<string, never>) => Promise<PluginContributionResult<T>>;
+};
+/** Define executable materialization once; each domain owns export validation and refusal wording.
+ * @param required - Existing manifest parser, module path, validator and complete refusal formatter.
+ * @param optional - Established read/import recovery policy; absent policies propagate I/O faults.
+ * @returns A definition whose installed loader always applies activation before importing code.
+ * @complexity O(1) composition; each load performs one contained import and one validation.
+ */
+export declare function defineExecutablePluginContribution<D, M>(required: {
+    readonly filename: string;
+    readonly contribution: string;
+    readonly parse: PluginContributionDefinition<D, LoadedPluginContribution<D, M>>['parse'];
+    readonly modulePath: (input: {
+        readonly descriptor: D;
+    }) => string;
+    readonly validate: (input: {
+        readonly exported: unknown;
+    }) => M | string;
+    readonly refusal: (input: {
+        readonly plugin: TrustedPluginPackage;
+        readonly descriptor: D;
+        readonly reason: string;
+    }) => string;
+}, optional?: {
+    readonly onReadError?: PluginContributionDefinition<D, LoadedPluginContribution<D, M>>['onReadError'];
+    readonly importRefusalReason?: string;
+    readonly importErrorReason?: string;
+}): PluginContributionDefinition<D, LoadedPluginContribution<D, M>>;
+//# sourceMappingURL=contribution-loader.d.ts.map

package/dist/lifecycle/contribution-loader.js

@@ -0,0 +1,92 @@
+/** Bind traversal to the lifecycle's existing trust/read/import owner. Parser and error policies
+ * remain contribution ports: manifests and refusal contracts do not change.
+ * @param required - Trusted-file effects, injectable for direct failure and ordering tests.
+ * @returns Installed and explicitly trusted source loaders; reads are fresh on each call.
+ * @complexity O(p + d) packages and declarations, plus their file/import I/O; O(d + r) output space.
+ */
+export function createPluginContributionLoader(required, _optional = {}) {
+    /** Source bypass is explicit: only the caller can establish that a source directory is trusted.
+     * Read faults propagate unless the definition supplies its established recovery policy. */
+    async function loadPluginContributionsFromSource(input, _options = {}) {
+        const { plugin, definition } = input;
+        let raw;
+        try {
+            raw = await required.readFile({ plugin, filename: definition.filename });
+        }
+        catch (error) {
+            const refusals = definition.onReadError?.({ plugin, error });
+            if (refusals === undefined)
+                throw error;
+            return { items: [], refusals };
+        }
+        const parsed = definition.parse({ raw });
+        if (!parsed.ok)
+            return { items: [], refusals: [`${definition.contribution} from '${plugin.pluginId}' were not loaded: ${definition.filename} is invalid: ${parsed.reason}`] };
+        const items = [];
+        const refusals = [];
+        for (const descriptor of parsed.descriptors) {
+            const loaded = await definition.load({ plugin, descriptor, importModule: required.importModule });
+            if (typeof loaded === 'string')
+                refusals.push(loaded);
+            else
+                items.push(loaded);
+        }
+        return { items, refusals };
+    }
+    /** Discover before loading, then interleave gate and manifest refusals in verdict order.
+     * Never fall back to source or bypass the bundled-digest gate for installed packages. */
+    async function loadPluginContributions(input, options = {}) {
+        const { definition } = input;
+        const { packageRefusal, requireActive = true, ...discovery } = options;
+        const verdicts = await required.findPackages({
+            ...discovery, workspaceId: input.workspaceId, filename: definition.filename,
+            contribution: definition.contribution, requireActive: definition.kind === 'executable' || requireActive,
+        });
+        const items = [];
+        const refusals = [];
+        for (const verdict of verdicts) {
+            if ('refusal' in verdict) {
+                refusals.push(verdict.refusal);
+                continue;
+            }
+            const refusal = packageRefusal?.({ plugin: verdict.trusted });
+            if (refusal !== undefined) {
+                refusals.push(refusal);
+                continue;
+            }
+            const loaded = await loadPluginContributionsFromSource({ plugin: verdict.trusted, definition });
+            items.push(...loaded.items);
+            refusals.push(...loaded.refusals);
+        }
+        return { items, refusals };
+    }
+    return { loadPluginContributions, loadPluginContributionsFromSource };
+}
+/** Define executable materialization once; each domain owns export validation and refusal wording.
+ * @param required - Existing manifest parser, module path, validator and complete refusal formatter.
+ * @param optional - Established read/import recovery policy; absent policies propagate I/O faults.
+ * @returns A definition whose installed loader always applies activation before importing code.
+ * @complexity O(1) composition; each load performs one contained import and one validation.
+ */
+export function defineExecutablePluginContribution(required, optional = {}) {
+    return {
+        filename: required.filename, contribution: required.contribution, kind: 'executable', parse: required.parse,
+        ...(optional.onReadError ? { onReadError: optional.onReadError } : {}),
+        load: async ({ plugin, descriptor, importModule }) => {
+            let module;
+            try {
+                const imported = await importModule({ plugin, modulePath: required.modulePath({ descriptor }) });
+                module = typeof imported === 'string' ? optional.importRefusalReason ?? imported : required.validate({ exported: imported.exported });
+            }
+            catch (error) {
+                if (optional.importErrorReason === undefined)
+                    throw error;
+                module = optional.importErrorReason;
+            }
+            if (typeof module === 'string')
+                return required.refusal({ plugin, descriptor, reason: module });
+            return { descriptor, pluginId: plugin.pluginId, module };
+        },
+    };
+}
+//# sourceMappingURL=contribution-loader.js.map

package/dist/lifecycle/fetch-archive.d.ts

@@ -1,6 +1,5 @@
 /**
- * Historical lifecycle rationale, carried with the implementation during consumer adoption.
- * @file The missing front half of the Agent Plugin install pipeline: URL -> verified bytes.
+ * @file The network front half of the Agent Plugin install pipeline: URL -> verified bytes.
  *
  * `install.ts` deliberately takes `archive: Uint8Array` and never a URL — it is a pure
  * verify/extract/publish step with no network surface at all. This module is the one place that

package/dist/lifecycle/index.d.ts

@@ -4,12 +4,13 @@ import type { AgentPluginLifecycleRequired, AgentPluginLifecycleOptional } from
 import type { AgentPluginDeliveryMode } from './resolve-agent-plugin-refs.js';
 import type { InstalledDigestIdentity } from './bundled-digests.js';
 export type { SeededAgentPluginOutcome, SeedBundledAgentPluginsRequired, SeedBundledAgentPluginsResult } from './seed-bundled.js';
-export type { RetireBundledAgentPluginsRequired, RetireBundledAgentPluginsOptional, RetiredAgentPluginOutcome } from './retire-bundled.js';
+export type { RetireBundledAgentPluginsRequired, RetireBundledAgentPluginsOptional, RetiredAgentPluginOutcome, RetiredAgentPluginSuccessorOutcome } from './retire-bundled.js';
 export * from './ports.js';
 export * from './layout.js';
 export * from './manifest.js';
 export * from './fetch-archive.js';
 export * from './mcp-provisioning.js';
+export * from './contribution-loader.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';
@@ -23,7 +24,7 @@ export type { AgentPluginArchiveEntry, AgentPluginArchiveReaderPort, AgentPlugin
 export type { AgentPluginIntegrity, InstallAgentPluginFromUrlRequired, InstallAgentPluginFromUrlOptional, InstalledAgentPluginFromUrl } from './install-from-url.js';
 export type { AgentPluginDeliveryMode, ResolveAgentPluginRefsResult } from './resolve-agent-plugin-refs.js';
 export type { SetAgentPluginEnabledInput, SetAgentPluginEnabledResult } from './set-enabled.js';
-export type { UninstallAgentPluginRequired, UninstallAgentPluginOptional, UninstallAgentPluginResult, AgentPluginUninstallPreview } from './uninstall.js';
+export type { UninstallAgentPluginRequired, UninstallAgentPluginOptional, UninstallAgentPluginResult, AgentPluginUninstallPreview, StagedTree } from './uninstall.js';
 export type { TrustedPluginPackage, TrustedPluginPackagesQuery, TrustedPluginVerdict } from './trusted-plugin-files.js';
 export type { AgentPluginSearchSkill, AgentPluginSearchCandidate, AgentPluginSearchMatch } from './search.js';
 /** One host context owns queues and effects. Keep this object and its ports stable for its lifetime.
@@ -67,12 +68,23 @@ export declare function createAgentPluginLifecycle(required: AgentPluginLifecycl
         readonly workspaceRoot: string;
         readonly pluginId: string;
     }) => Promise<boolean>;
-    installAgentPlugin: (required: import("./install.js").InstallAgentPluginRequired, _optional?: import("./install.js").InstallAgentPluginOptional) => Promise<import("./types.js").InstalledAgentPlugin>;
+    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>;
     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>;
+    stageForRemoval: (input: {
+        readonly packagesDir: string;
+        readonly packageRoot: string;
+    }, _optional?: Record<string, never>) => Promise<import("./uninstall.js").StagedTree>;
+    restoreStagedTrees: (input: {
+        readonly staged: Parameters<(staged: readonly import("./uninstall.js").StagedTree[], cause: unknown) => Promise<unknown>>[0];
+        readonly cause: unknown;
+    }, _optional?: Record<string, never>) => Promise<unknown>;
+    removeFrozenPackageTree: (input: {
+        readonly root: string;
+    }, _optional?: Record<string, never>) => Promise<void>;
     isAgentPluginActive: (input: {
         readonly activations: Parameters<(activations: import("./activation.js").AgentPluginActivations, pluginId: string) => boolean>[0];
         readonly pluginId: string;
@@ -137,8 +149,18 @@ export declare function createAgentPluginLifecycle(required: AgentPluginLifecycl
     }, optional?: {
         readonly deliveryMode?: AgentPluginDeliveryMode;
     }) => Promise<import("./resolve-agent-plugin-refs.js").ResolveAgentPluginRefsResult>;
+    pluginMemory: (input: {
+        readonly workspaceId: string;
+        readonly pluginId: string;
+    }) => import("../../core/persistent-state.js").PluginMemory;
+    migratePluginLayout: (input: {
+        readonly workspaceId: string;
+    }) => Promise<{
+        complete: boolean;
+        moved: number;
+    }>;
     listInstalledPlugins: (input: {
-        readonly packagesDir: string;
+        readonly workspaceRoot: string;
     }) => Promise<readonly import("./types.js").InstalledAgentPlugin[]>;
     isInstalledDigestPresent: (input: {
         readonly packagesDir: string;
@@ -170,5 +192,13 @@ export declare function createAgentPluginLifecycle(required: AgentPluginLifecycl
         readonly sourceDir: string;
     }) => Promise<import("./bundled-source-archive.js").PackedAgentPluginArchive>;
     createBundledSourceArchiveReader: (_input: Record<string, never>) => import("./install.js").AgentPluginArchiveReaderPort;
+    loadPluginContributions: <D, T>(input: {
+        readonly workspaceId: string;
+        readonly definition: import("./contribution-loader.js").PluginContributionDefinition<D, T>;
+    }, options?: import("./contribution-loader.js").LoadPluginContributionsOptional) => Promise<import("./contribution-loader.js").PluginContributionResult<T>>;
+    loadPluginContributionsFromSource: <D, T>(input: {
+        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>>;
 };
 //# sourceMappingURL=index.d.ts.map