@jini-ai/agent-plugins 0.4.1 → 0.4.3

package/dist/lifecycle/install.js

@@ -1,9 +1,82 @@
+import { listInstalledPackageRoots } from "./installed-package-roots.js";
+import { createUninstallModule } from "./uninstall.js";
+import { readPluginIdentity, assertPluginIdentityAvailable } from "@jini-ai/core/plugin-directory";
+/**
+ * @file `installAgentPlugin()` — content-addressed, adversarially-hardened extraction of one Agent
+ * Plugin (agent-plugins.org) archive into one workspace's own `AgentPluginWorkspaceLayout.packages`.
+ *
+ * This is the highest-risk unit in the whole feature. Extraction is where containment actually
+ * breaks — everything downstream (capability projection, a future MCP admission gate) trusts that a
+ * "package root" is exactly the bytes the archive declared, laid out exactly where the archive said,
+ * with nothing outside it touched. Two independently-cited attack classes drive the checks here:
+ *
+ * - **Zip-slip / archive-extraction path traversal** (Snyk's zip-slip research; JFrog's
+ *   `mholt/archiver` writeup; the `node-tar` GHSA-8qq5-rm4j-mr97 advisory) has two vectors: a
+ *   crafted entry NAME containing `../` (caught by {@link normalizePackageEntryPath}'s lexical
+ *   check), and a crafted SYMLINK entry whose target a later, innocent-looking entry name walks
+ *   through. The convergent ecosystem fix for the second vector — and the one this module takes — is
+ *   to refuse symlink entries outright rather than attempt to validate where they point: a plugin
+ *   has no legitimate reason to ship a symlink inside its own package, and the Agent Plugins spec's
+ *   own path-safety clause only ever promises symlinks MAY resolve inside the root, never that a
+ *   client must accept one.
+ * - **Decompression bombs**, in both the classic "one file lies about its size" shape (caught by
+ *   bounding bytes actually observed leaving `openReadStream()`, not the archive's own declared
+ *   size) and the "many small files" shape (caught by a running total across the whole archive).
+ *
+ * Why this is a SEPARATE format from the host runtime-plugin format's loader (`plugin-runtime/loader.ts`), not a
+ * shared one: verified against that file directly. `loadPlugin()`'s BR-01 pipeline requires
+ * `manifest.integrity` (a per-file SHA-256 map), `manifest.sdkRange` checked against a runtime
+ * the host plugin SDK version, and a `server/index.mjs` ESM entry point it `import()`s. An Agent Plugin has
+ * none of those — no integrity map, no SDK range, no single entry point, and (per this feature's own
+ * FINAL decision) no code the host ever imports or executes at all in v1: Skills are markdown read for
+ * context injection, and MCP servers are preview-only (`capability-projection.ts`). Adapting Agent
+ * Plugins into `loadPlugin()`'s pipeline would mean inventing values for fields the open standard
+ * does not define, which is precisely the "package format vs. execution/trust model" conflation this
+ * feature's own owner-locked decisions (see `CTX-AGENTPLUGINS-2026-08-12.md` F2) rule out.
+ *
+ * Why the archive itself is a `ArchiveReaderPort`, not a concrete zip/tar library call: this
+ * codebase's own port+adapter discipline (`mcp-federation/ports.ts`'s `McpSessionPort`/
+ * `McpStdioChannel` split is the direct precedent) — and, concretely, no zip/tar dependency exists
+ * in this repo's `package.json` today. Choosing and vetting one (license, maintenance, streaming
+ * support) is a real decision outside a Programmer's scope to make silently; this module declares
+ * the seam and is exercised end-to-end by a scripted double, so a real adapter is a pure addition
+ * with zero change to the hardening logic here. See the handoff's REMAINING section.
+ *
+ * Content-addressing (`ws/<workspaceId>/packages/sha256/<archiveDigest>/`): the digest is verified
+ * BEFORE extraction ever touches the archive reader, so an install with a mismatched digest never
+ * even attempts to unpack — the digest is the trust boundary between "bytes a marketplace claimed"
+ * and "bytes this process is willing to run a parser over". A second install of byte-identical
+ * content BY THE SAME WORKSPACE is recognized from the digest alone and short-circuits without a
+ * second extraction. Deliberately NOT shared across workspaces — see `layout.ts`'s header (owner
+ * decision, tenant-grade isolation, 2026-08-12): this function resolves the workspace-scoped layout
+ * itself, exactly once, from an instance-level `AgentPluginLayout` plus one `workspaceId` (see the
+ * SECURITY note on {@link InstallAgentPluginRequired} below) — the caller is what makes two
+ * different workspaces' installs land in disjoint trees, simply by supplying a different
+ * `workspaceId` for each; this function's own internal `forWorkspace()` call is what turns that into
+ * disjoint, internally-consistent paths.
+ *
+ * Architectural role:
+ * The one place this feature performs filesystem writes for installed package bytes. No network I/O
+ * (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";
 /** 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 { parseAgentPluginManifest as parseAgentPluginManifestValue } from "./manifest.js";
+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 {
@@ -25,7 +98,7 @@ 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 });
+    const parseAgentPluginManifest = (value) => parseAgentPluginManifestValue({ value }, { identityNamespace: ports.extensionNamespace });
     const { assertContainedOnDisk, normalizePackageEntryPath } = createPackagePathsModule(ports);
     const LIMITS = {
         maxArchiveBytes: 32 * 1024 * 1024,
@@ -33,11 +106,89 @@ function buildModule(ports) {
         maxFileBytes: 16 * 1024 * 1024,
         maxTotalExtractedBytes: 64 * 1024 * 1024,
     };
+    /** Publisher ids are metadata, never filesystem segments. The workspace identity lock
+     * serializes installs under different local names competing for one qualified id.
+     * @complexity O(d) manifest reads for d installed revisions; no executable imports. */
+    async function assertIdentityAvailable(workspaceRoot, candidate) {
+        // Installed roots are canonical paths; compare against the same root even when the host
+        // supplied an OS alias (macOS /var -> /private/var). Containment still rejects escaped links.
+        workspaceRoot = await ports.filesystem.realpath(workspaceRoot);
+        for (const root of await listInstalledPackageRoots({ ports, workspaceRoot })) {
+            const manifestPath = path.join(root.packageRoot, 'plugin.json');
+            await persistentState.assertOwnedPath({ workspaceRoot, entryPath: path.relative(workspaceRoot, manifestPath) });
+            let raw;
+            let identity;
+            try {
+                raw = JSON.parse(await readFile(manifestPath, 'utf8'));
+                identity = readPluginIdentity({ manifest: raw, name: root.localId, namespace: ports.extensionNamespace });
+            }
+            catch {
+                // A damaged unrelated install must not block fresh installs or bundled seeding.
+                ports.onEvent?.({ event: 'agent-plugin-identity-warning', message: `Plugin '${root.localId}': installed identity manifest is unreadable or invalid; omitted from identity admission.` });
+                continue;
+            }
+            try {
+                assertPluginIdentityAvailable({ candidate: { id: candidate.id, localId: candidate.pluginId, family: 'agent-plugin' },
+                    installed: [{ ...identity, localId: root.localId, family: 'agent-plugin', version: typeof raw.version === 'string' ? raw.version : null, enabled: false }] });
+            }
+            catch {
+                throw new AgentPluginInstallError({ code: 'PLUGIN_ID_CONFLICT', message: 'The publisher-qualified plugin id conflicts with an installed package.' });
+            }
+        }
+    }
+    /** Retires only this plugin's superseded revisions after accepted publication, under the same
+     * identity/plugin locks. Persistent data, learned facts and notes never enter this operation.
+     * Reuse uninstall's frozen-tree staging so an interrupted removal is no longer a live digest.
+     * There is no previous-revision rollback slot in this lifecycle; failed publication keeps all
+     * prior bytes. Cleanup faults warn without turning an accepted install into a failed install.
+     * @complexity O(d + f), d workspace revisions, f files in this plugin's superseded packages.
+     */
+    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)
+                    continue;
+                try {
+                    const staged = await removal.stageForRemoval(path.dirname(root.packageRoot), root.packageRoot);
+                    await removal.removeFrozenPackageTree(staged.quarantined);
+                }
+                catch {
+                    ports.onEvent?.({ event: 'agent-plugin-revision-prune-warning', message: `Plugin '${installed.pluginId}': a superseded revision could not be pruned.` });
+                }
+            }
+        }
+        catch {
+            ports.onEvent?.({ event: 'agent-plugin-revision-prune-warning', message: `Plugin '${installed.pluginId}': superseded revisions could not be scanned for pruning.` });
+        }
+    }
+    /** Exposes `LIMITS.maxArchiveBytes` for a caller outside this module — concretely, a test asserting
+   * `@jini-ai/agent-plugins/lifecycle`'s fetch cap constant stays pinned to this one. The local fetch-archive.ts fork was deleted; see the package's fetch module
+   * for why it duplicates the number instead of importing it (no runtime dependency on `install.ts`);
+   * this accessor is what lets a test assert the pairing without either module importing the other. */
     function maxAgentPluginInstallArchiveBytes() {
         return LIMITS.maxArchiveBytes;
     }
     const SHA256_HEX_PATTERN = /^[a-f0-9]{64}$/;
-    async function installAgentPlugin(required, _optional = {}) {
+    /**
+   * Verifies, extracts, and publishes one Agent Plugin archive.
+   *
+   * @throws {AgentPluginInstallError} For every expected failure — a hostile or malformed archive, a
+   * digest mismatch, an invalid manifest. Never partially publishes: any failure after extraction has
+   * begun removes the whole staging directory before rethrowing.
+   * @complexity O(e) in archive entry count, O(b) in total extracted bytes — both explicitly bounded
+   * by {@link LIMITS}, so this function's cost cannot be driven unbounded by a hostile archive.
+   */
+    // The ONE call that turns (instance layout, workspaceId) into real, internally-consistent
+    // packages/staging/pluginDataDir paths — see the SECURITY note on `InstallAgentPluginRequired.layout`
+    // above for why this replaces accepting an already-resolved `AgentPluginWorkspaceLayout` directly.
+    // `forWorkspace` itself still throws for a syntactically invalid `workspaceId`, unchanged.
+    // Whether this install succeeded (bytes now live at `finalRoot`) or failed, the staging
+    // transaction directory itself must never be left behind — on success `rename` already moved
+    // `extractionRoot` out of it, so this only ever removes the (now-empty, or failure-abandoned)
+    // temp directory, never the published package.
+    async function installAgentPlugin(required, optional = {}) {
         const { archive, expectedSha256, archiveReader, layout, workspaceId } = required;
         const workspaceLayout = layout.forWorkspace({ workspaceId });
         if (archive.byteLength > LIMITS.maxArchiveBytes) {
@@ -57,34 +208,73 @@ function buildModule(ports) {
         try {
             const executablePaths = await extractEntries(archiveReader.entries({ archive }), extractionRoot);
             const indexed = await indexInstalledRoot(extractionRoot, digest);
-            return await persistentState.withPluginLock({ workspaceRoot: workspaceLayout.root, pluginId: indexed.pluginId, run: async () => {
-                    // The manifest identifies the plugin only after bounded staging extraction (Layout B).
-                    const pluginId = indexed.pluginId;
-                    const packagesDir = workspaceLayout.pluginPackagesDir({ pluginId });
-                    await persistentState.assertOwnedPath({ workspaceRoot: workspaceLayout.root, entryPath: path.relative(workspaceLayout.root, packagesDir) });
-                    await mkdir(packagesDir, { recursive: true, mode: 0o700 });
-                    const finalRoot = await assertContainedOnDisk(packagesDir, digest);
-                    for (const directory of [workspaceLayout.pluginDataDir({ pluginId }),
-                        workspaceLayout.pluginMemoryDir({ pluginId, kind: 'learned' }),
-                        workspaceLayout.pluginMemoryDir({ pluginId, kind: 'notes' })]) {
-                        await persistentState.assertOwnedPath({ workspaceRoot: workspaceLayout.root, entryPath: path.relative(workspaceLayout.root, directory) });
-                        await mkdir(directory, { recursive: true, mode: 0o700 });
-                    }
-                    if (await isRealDirectory(finalRoot))
-                        return indexInstalledRoot(finalRoot, digest);
-                    await publish(extractionRoot, finalRoot);
-                    await freezeTree(finalRoot, executablePaths);
-                    return { ...indexed, packageRoot: finalRoot };
+            if (optional.previewOnly)
+                return indexed;
+            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 () => {
+                            // 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
+                            // in package docs. Package extension files never seed learned memory or the user's notes.
+                            // Content-addressed dedup, scoped to THIS workspace's own tree (`workspaceLayout` was just
+                            // resolved above, atomically, from this same `workspaceId`): identical bytes were already
+                            // extracted, verified, and frozen by a prior install of this same workspace's — never
+                            // re-extracted for a different workspace, by construction, since a different workspace's
+                            // `workspaceLayout.packages` is a different path entirely. one bounded staging extraction precedes this check.
+                            // Publish BEFORE freezing permissions, not after: `rename()` moves `extractionRoot` as a single
+                            // directory-entry operation, and on this filesystem renaming an already-read-only (0o555)
+                            // directory itself fails EACCES (observed, not merely theoretical — see the regression test this
+                            // ordering fixed). Freezing after publish also closes a smaller race for free: nothing outside
+                            // this function can observe the package at its live path while it is still writable, because the
+                            // live path does not exist until `publish` returns.
+                            let publishedPlugin;
+                            const publishPackage = async () => {
+                                // The manifest identifies the plugin only after bounded staging extraction (Layout B).
+                                const pluginId = indexed.pluginId;
+                                const packagesDir = workspaceLayout.pluginPackagesDir({ pluginId });
+                                await persistentState.assertOwnedPath({ workspaceRoot: workspaceLayout.root, entryPath: path.relative(workspaceLayout.root, packagesDir) });
+                                await mkdir(packagesDir, { recursive: true, mode: 0o700 });
+                                const finalRoot = await assertContainedOnDisk(packagesDir, digest);
+                                for (const directory of [workspaceLayout.pluginDataDir({ pluginId }),
+                                    workspaceLayout.pluginMemoryDir({ pluginId, kind: 'learned' }),
+                                    workspaceLayout.pluginMemoryDir({ pluginId, kind: 'notes' })]) {
+                                    await persistentState.assertOwnedPath({ workspaceRoot: workspaceLayout.root, entryPath: path.relative(workspaceLayout.root, directory) });
+                                    await mkdir(directory, { recursive: true, mode: 0o700 });
+                                }
+                                if (await isRealDirectory(finalRoot)) {
+                                    publishedPlugin = await indexInstalledRoot(finalRoot, digest);
+                                    return publishedPlugin;
+                                }
+                                await publish(extractionRoot, finalRoot);
+                                await freezeTree(finalRoot, executablePaths);
+                                /** Absolute, read-only (frozen) path to the extracted package root. */
+                                publishedPlugin = { ...indexed, packageRoot: finalRoot };
+                                return publishedPlugin;
+                            };
+                            const installed = await (optional.publishGuard ? optional.publishGuard({ plugin: indexed, publish: publishPackage }, {}) : publishPackage());
+                            if (publishedPlugin)
+                                await pruneSupersededRevisions({ workspaceRoot: workspaceLayout.root, installed: publishedPlugin });
+                            return installed;
+                        } });
+                    if (ports.identityAdmission)
+                        return ports.identityAdmission({ id: indexed.id, localId: indexed.pluginId, run: publishWithinPluginLock }, {});
+                    return publishWithinPluginLock();
                 } });
         }
         finally {
             await rm(transactionRoot, { recursive: true, force: true });
         }
     }
+    /** The `(target '...')` suffix on the symlink-rejection message, or nothing when the entry carries
+   * no `linkTarget` at all — split out purely to keep that `&&`/ternary pair out of
+   * {@link extractOneEntry}'s own branch count. */
     function symlinkRejectionMessage(entry) {
         const targetSuffix = "linkTarget" in entry && entry.linkTarget ? ` (target '${entry.linkTarget}')` : "";
         return `archive entry '${entry.entryPath}' has kind '${entry.kind}', which Agent Plugin packages are not permitted to contain${targetSuffix}`;
     }
+    /** `normalizePackageEntryPath()`, with its thrown error re-shaped into the module's own
+   * `AgentPluginInstallError` vocabulary. */
     function normalizeEntryPathOrThrow(entryPath) {
         try {
             return normalizePackageEntryPath(entryPath);
@@ -93,6 +283,7 @@ function buildModule(ports) {
             throw new AgentPluginInstallError({ code: "UNSAFE_ENTRY_PATH", message: `archive entry path is unsafe: '${entryPath}'` }, { cause: error });
         }
     }
+    /** `assertContainedOnDisk()`, with its thrown error re-shaped the same way. */
     async function resolveContainedDestinationOrThrow(extractionRoot, normalized) {
         try {
             return await assertContainedOnDisk(extractionRoot, normalized);
@@ -103,6 +294,15 @@ function buildModule(ports) {
             });
         }
     }
+    /**
+   * Applies every hardening rule in this module's header to one archive entry: symlink rejection,
+   * path normalization, duplicate detection, containment, the per-file size cap, and (for a file
+   * entry) the actual write. Returns the running total-extracted-bytes count, since that is the one
+   * piece of `extractEntries`'s loop state a single entry's processing can change.
+   */
+    // Refused BEFORE path normalization: a symlink entry is never acceptable regardless of how
+    // "safe" its own name looks, matching the ecosystem fix this module's header cites — validating
+    // where a permitted symlink might point is more attack surface than refusing the entry kind.
     async function extractOneEntry(args) {
         const { entry, extractionRoot, seen, executablePaths, totalBytesSoFar } = args;
         if (entry.kind !== "file" && entry.kind !== "directory") {
@@ -139,6 +339,8 @@ function buildModule(ports) {
      * its entries from the archive bytes, so a second iteration costs one central-directory walk
      * and opens no content stream.
      */
+    /** Ported from Jini 78d4b60b: reject from metadata before a staging transaction exists.
+   * A second central-directory walk opens no content streams and avoids over-cap disk churn. */
     async function assertEntryCountWithinCap(entries) {
         let entryCount = 0;
         for await (const _entry of entries) {
@@ -150,6 +352,9 @@ function buildModule(ports) {
     function tooManyEntriesError() {
         return new AgentPluginInstallError({ code: "TOO_MANY_ENTRIES", message: `archive exceeds the ${LIMITS.maxEntries}-entry cap` });
     }
+    /** Extracts every entry into `extractionRoot`, enforcing every hardening rule in this module's
+   * header. Returns the set of archive-relative paths the archive marked executable, for
+   * {@link freezeTree} to preserve the `+x` bit on. */
     async function extractEntries(entries, extractionRoot) {
         const seen = new Set();
         const executablePaths = new Set();
@@ -164,6 +369,12 @@ function buildModule(ports) {
         }
         return executablePaths;
     }
+    /** Streams one file entry to disk, bounding both its own size and the running archive total against
+   * bytes ACTUALLY observed — never the archive format's declared size, which a decompression bomb
+   * lies about by construction. `O_EXCL` refuses to write over anything already at `destination`
+   * (there cannot legitimately be one — `extractEntries`'s duplicate check already refused a second
+   * entry for the same path); `O_NOFOLLOW` refuses to follow a final-component symlink if the
+   * filesystem somehow already had one (defense in depth — this module never creates one itself). */
     async function writeContainedFile(params) {
         let flags = constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL;
         if (ports.process.platform !== "win32")
@@ -189,7 +400,36 @@ function buildModule(ports) {
         }
         return totalBytes;
     }
-    async function indexInstalledRoot(packageRoot, archiveDigest) {
+    /** 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");
@@ -212,6 +452,8 @@ function buildModule(ports) {
             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 })) {
@@ -225,22 +467,49 @@ function buildModule(ports) {
                     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,
-            ...(parsed.manifest.description !== undefined ? { description: parsed.manifest.description } : {}),
+            ...( /**
+         * `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
+   * silently dropped for whenever it is).
+   *
+   * Stated plainly rather than implied (`mcp-federation/trust.ts`'s own "what this tier deliberately
+   * does NOT claim" discipline): this is best-effort defense against an ACCIDENTAL same-process write
+   * into what is supposed to be a read-only `PLUGIN_ROOT`, not a security boundary against a
+   * determined attacker already running code as this same OS user — that user can `chmod` again. */
     async function freezeTree(root, executables, prefix = "") {
         for (const entry of await readdir(root, { withFileTypes: true })) {
             const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
@@ -255,6 +524,13 @@ function buildModule(ports) {
         }
         await chmod(root, 0o555);
     }
+    /** Publishes `extractionRoot` to `finalRoot` by rename — atomic on the same filesystem, so a reader
+     * can never observe a partially-extracted package at the live path. Tolerates losing a race against
+     * a concurrent install of the byte-identical digest (the same content, published a moment earlier by
+     * another process) rather than treating that as a failure. */
+    // macOS reports EACCES, rather than ENOTEMPTY, when the winning install has already
+    // frozen its destination directory. Still require a real directory below: a permission
+    // failure with no published winner must remain PUBLISH_FAILED.
     async function publish(extractionRoot, finalRoot) {
         try {
             await rename(extractionRoot, finalRoot);
@@ -266,6 +542,8 @@ function buildModule(ports) {
             if (!(await isRealDirectory(finalRoot))) {
                 throw new AgentPluginInstallError({ code: "PUBLISH_FAILED", message: `'${finalRoot}' exists but is not a real, published package directory` }, { cause: error });
             }
+            // Lost the race to a concurrent install of identical bytes — the bytes at `finalRoot` are the
+            // ones this install itself would have written, so this is not a failure.
         }
     }
     async function isRealDirectory(target) {

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

@@ -0,0 +1,16 @@
+import type { AgentPluginLifecyclePorts } from './ports.js';
+export declare const INSTALLED_PLUGIN_DIGEST_PATTERN: RegExp;
+export interface InstalledPackageRoot {
+    readonly localId: string;
+    readonly archiveDigest: string;
+    readonly packageRoot: string;
+}
+/** Enumerates contained installed revisions; missing stores are empty. A corrupt slot is
+ * isolated, matching the full installed-plugin index's existing recovery contract.
+ * @complexity O(d) directory/containment operations for d revisions; no executable imports.
+ */
+export declare function listInstalledPackageRoots({ ports, workspaceRoot }: {
+    ports: AgentPluginLifecyclePorts;
+    workspaceRoot: string;
+}, _optional?: Record<string, never>): Promise<readonly InstalledPackageRoot[]>;
+//# sourceMappingURL=installed-package-roots.d.ts.map

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

@@ -0,0 +1,55 @@
+/** The installed-package walk shared by full indexing and identity admission. Reusing this
+ * traversal preserves the same digest grammar, memory-folder exclusion and containment checks. */
+import path from 'node:path';
+import { createPersistentStateModule } from './persistent-state.js';
+import { createPackagePathsModule } from './package-paths.js';
+export const INSTALLED_PLUGIN_DIGEST_PATTERN = /^[a-f0-9]{64}$/;
+/** Enumerates contained installed revisions; missing stores are empty. A corrupt slot is
+ * isolated, matching the full installed-plugin index's existing recovery contract.
+ * @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);
+    let folders;
+    try {
+        folders = await readdir(workspaceRoot, { withFileTypes: true });
+    }
+    catch (error) {
+        if (isEnoent(error))
+            return [];
+        throw error;
+    }
+    const roots = [];
+    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;
+        try {
+            await persistentState.assertOwnedPath({ workspaceRoot, entryPath: path.relative(workspaceRoot, packagesDir) });
+            entries = await readdir(packagesDir, { withFileTypes: true });
+        }
+        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.
+            }
+        }
+    }
+    return roots;
+}
+/** Only a genuinely missing store is empty; other filesystem faults propagate unchanged. */
+function isEnoent(error) {
+    return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+//# sourceMappingURL=installed-package-roots.js.map

package/dist/lifecycle/layout.js

@@ -1,5 +1,5 @@
 import path from 'node:path';
-import { pluginStatePaths } from '../../persistent-state.js';
+import { pluginStatePaths } from '../../core/persistent-state.js';
 /** Explicit root only; site-root and environment resolution belong to the consumer. */
 export function createAgentPluginLayout(required) {
     if (!path.isAbsolute(required.root))

package/dist/lifecycle/manifest.d.ts

@@ -1,63 +1,3 @@
-/**
- * Historical lifecycle rationale, carried with the implementation during consumer adoption.
- * @file `parseAgentPluginManifest()` / `parseAgentPluginMcpConfig()` — the Agent Plugins v1.0.0
- * `plugin.json` / `mcp.json` grammar (agent-plugins.org/specification), verified against the live
- * spec rather than inferred from an example manifest.
- *
- * Deliberately a SEPARATE, smaller validator from `src/features/plugin-runtime/manifest.ts`'s
- * `validateManifest()`. That file validates `.host-plugin`'s own tarball format — `integrity`
- * (per-file SHA-256), `sdkRange`, `tier`, an exactly-three-token capability vocabulary, a single
- * `content.entry.beforeSave` hook. This file validates the OPEN standard's `plugin.json`, which
- * shares none of those fields and defines no execution/trust/capability model at all — see this
- * feature's own header comment in `install.ts` for why the two formats cannot be unified.
- *
- * Spec facts this module encodes, quoted/paraphrased from agent-plugins.org/specification (verified
- * 2026-08-12, not carried forward from an earlier round's inference):
- * - `plugin.json`'s `name`: 1-64 chars, lowercase alphanumeric/hyphen/period only, must start and
- *   end alphanumeric, no `--` or `..` consecutive delimiters (§5.5). Valid: `my-plugin`,
- *   `acme.tools`, `lint3r`, `a`. Invalid: `My-Plugin`, `-start`, `has--double`.
- * - `plugin.json`'s `$schema` MUST equal `https://agent-plugins.org/schemas/1.0.0/plugin.schema.json`
- *   for this pinned version; `mcp.json`'s MUST equal
- *   `https://agent-plugins.org/schemas/1.0.0/mcp.schema.json`.
- * - Unknown top-level `plugin.json` fields produce warnings but do not block loading — this module
- *   returns them as `warnings`, never as a rejection reason.
- * - `mcp.json`'s top-level shape is `{ "$schema": ..., "mcpServers": { "<server-id>": {...} } }` —
- *   `mcpServers` MUST be an object whose member names identify servers.
- * - Each server entry MUST carry a `type` discriminator matching exactly one of three CLOSED
- *   variants (re-verified live against `agent-plugins.org/schemas/1.0.0/mcp.schema.json` and
- *   `/specification`, 2026-09-10 — superseding this file's earlier "not validated, no caller needs
- *   it" note, which is now false: `capability-projection.ts`'s MCP-server descriptors are no longer
- *   unconditionally `execute: { kind: "unavailable" }`, and launching a server needs its real
- *   transport config, not just its id):
- *     - `stdio`: requires `command` (non-empty string); optional `args` (string[]), `env`
- *       (string-valued object — MUST NOT set `PLUGIN_ROOT`/`PLUGIN_DATA`, which the spec reserves),
- *       `cwd` (plugin-relative path).
- *     - `streamable-http` / `sse`: requires `url` (non-empty string); optional `headers`
- *       (string-valued object).
- * - **The spec defines NO auth-related field on a server entry at all.** Verbatim from
- *   `/specification`: "Agent Plugins v1 defines no OAuth configuration or portable
- *   credential-reference fields. Authorization discovery, user interaction, and credential storage
- *   are client-managed." A plugin therefore cannot declare "this server needs OAuth" using any
- *   spec-defined field — the host is the client the spec defers that decision to. This module accepts
- *   the host-specific metadata in `plugin.json`'s `extensions.<host-namespace>.mcpServers[serverId]`, keeping
- *   `mcp.json` transport entries closed per §7.2.1. Hosts may translate legacy auth and sign-in defaults in MCP
- *   entries through readServerMetadata for existing packages, but those cannot supply operator read trust.
- *   `authMode: "oauth" | "none"` selects client auth; absent defaults to "none".
- *   `defaultTools: { allow?, write?, read? }` names sign-in grants and reviewed read tools.
- *   `write` requires `allow` and must be its subset; `read` must be a subset when `allow` is
- *   present. A read-only declaration without `allow` leaves sign-in grants unchanged.
- *   Remote hints may veto a read declaration but never supply it. A third,
- *   `tokenAuth: { helpUrl, probeUrl }`, offers a pasted access token as the sign-in fallback
- *   (`access-token-tool.ts`). A fourth, `renamedTools: { oldName: newName }`, carries saved tool
- *   selections across a vendor's tool rename (`apply-tool-renames.ts`). A malformed per-server entry
- *   (wrong/missing `type`, missing required field) does not fail the whole file — see
- *   `ParseAgentPluginMcpConfigResult`'s own doc for the fail-open contract this preserves.
- *
- * Architectural role:
- * Pure, no-I/O parsing over an already-`JSON.parse`d value — mirrors `plugin-runtime/manifest.ts`'s
- * own "receives a JS value, never a file path or raw bytes" contract. `install.ts` is the only
- * caller that reads the file and hands the parsed value here.
- */
 export { validatePluginManifest, validateMcpManifest } from '../manifest.js';
 export type { PluginManifest, McpManifest, McpServerEntry } from '../manifest.js';
 import type { PluginManifestAuthor } from '../manifest.js';
@@ -76,6 +16,9 @@ export interface AgentPluginManifest {
     readonly license?: (string) | undefined;
     readonly keywords?: (readonly string[]) | undefined;
     readonly extensions?: (Readonly<Record<string, unknown>>) | undefined;
+    /** Normalized publisher identity, independent of name/storage key and version. */
+    readonly id?: string | undefined;
+    readonly provides?: readonly string[] | undefined;
 }
 export type ParseAgentPluginManifestResult = {
     readonly ok: true;
@@ -95,6 +38,8 @@ export type ParseAgentPluginManifestResult = {
  */
 export declare function parseAgentPluginManifest({ value }: {
     readonly value: unknown;
+}, { identityNamespace }?: {
+    readonly identityNamespace?: string;
 }): ParseAgentPluginManifestResult;
 /**
  * The three closed transport variants `mcp.schema.json` v1.0.0 defines. See this file's header for