@jini-ai/agent-plugins 0.4.1 → 0.4.2

package/dist/lifecycle/index.js

@@ -13,12 +13,14 @@ import { createResolveAgentPluginRefsModule } from './resolve-agent-plugin-refs.
 import { createSearchModule } from './search.js';
 import { createSetEnabledModule } from './set-enabled.js';
 import { createTrustedPluginFilesModule } from './trusted-plugin-files.js';
+import { createPluginContributionLoader } from './contribution-loader.js';
 import { createUninstallModule } from './uninstall.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';
@@ -46,8 +48,14 @@ export function createAgentPluginLifecycle(required, optional = {}) {
     const search = createSearchModule(context);
     const enabled = createSetEnabledModule(context);
     const trusted = createTrustedPluginFilesModule(context);
+    const contributions = createPluginContributionLoader({
+        findPackages: input => trusted.findTrustedPluginPackages(input),
+        readFile: ({ plugin, filename }) => trusted.readTrustedPluginFile(plugin, filename),
+        importModule: ({ plugin, modulePath }) => trusted.importContainedModule(plugin, modulePath),
+    });
     const uninstall = createUninstallModule(context);
     return {
+        ...contributions,
         fetchAgentPluginArchive: (input, optional = {}) => fetchAgentPluginArchive({ ...input, fetch: context.fetch, outboundGuard: context.outboundGuard }, optional),
         maxAgentPluginArchiveBytes,
         seedBundledAgentPlugins: createSeedBundledModule(context).seedBundledAgentPlugins,
@@ -64,6 +72,9 @@ export function createAgentPluginLifecycle(required, optional = {}) {
         findTrustedPluginPackages: (input, optional = {}) => trusted.findTrustedPluginPackages({ ...input, ...optional }),
         previewAgentPluginUninstall: uninstall.previewAgentPluginUninstall,
         uninstallAgentPlugin: uninstall.uninstallAgentPlugin,
+        stageForRemoval: (input, _optional = {}) => uninstall.stageForRemoval(input.packagesDir, input.packageRoot),
+        restoreStagedTrees: (input, _optional = {}) => uninstall.restoreStagedTrees(input.staged, input.cause),
+        removeFrozenPackageTree: (input, _optional = {}) => uninstall.removeFrozenPackageTree(input.root),
         isAgentPluginActive: (input) => activation.isAgentPluginActive(input.activations, input.pluginId),
         filterActiveAgentPlugins: (input) => activation.filterActiveAgentPlugins(input.activations, input.items, item => input.pluginIdOf({ item })),
         readAgentPluginActivations: (input) => activation.readAgentPluginActivations(input.workspaceRoot),

package/dist/lifecycle/install-from-url.d.ts

@@ -1,20 +1,17 @@
 /**
- * Historical lifecycle rationale, carried with the implementation during consumer adoption.
  *
- * Host command-line rationale retained when the unused URL-install CLI was removed:
+ * Caller integrity constraints:
  * - A digest-only preview downloads and reports SHA-256 without installing. Hashing those bytes
  *   does not establish provenance; the host must make that distinction visible to the operator.
  * - A real install requires exactly one explicit integrity decision: an independent pinned digest
  *   or trust-on-first-use. Missing or conflicting choices must be refused before execution, with
  *   diagnostics naming the choice the operator needs to supply.
- * - Keep pure token classification separate from argument validation and exit/reporting effects,
- *   so both parsing and legal combinations are directly testable without a network or process exit.
  * - The CLI composes shared download/extraction operations; digest verification, expansion bounds,
  *   path containment and tenant isolation belong in those operations rather than a CLI-only guard.
  * @file The one composition step that turns "here is an address" into "the plugin is on this
  * machine": {@link fetchAgentPluginArchive} -> `installAgentPlugin`.
  *
- * This is the caller `install.ts` was written for and never had. It adds no extraction, path, or
+ * It adds no extraction, path, or
  * manifest logic of its own — every one of those guarantees still comes from `install.ts`, reached
  * with bytes instead of a URL.
  *

package/dist/lifecycle/install-from-url.js

@@ -1,20 +1,17 @@
 /**
- * Historical lifecycle rationale, carried with the implementation during consumer adoption.
  *
- * Host command-line rationale retained when the unused URL-install CLI was removed:
+ * Caller integrity constraints:
  * - A digest-only preview downloads and reports SHA-256 without installing. Hashing those bytes
  *   does not establish provenance; the host must make that distinction visible to the operator.
  * - A real install requires exactly one explicit integrity decision: an independent pinned digest
  *   or trust-on-first-use. Missing or conflicting choices must be refused before execution, with
  *   diagnostics naming the choice the operator needs to supply.
- * - Keep pure token classification separate from argument validation and exit/reporting effects,
- *   so both parsing and legal combinations are directly testable without a network or process exit.
  * - The CLI composes shared download/extraction operations; digest verification, expansion bounds,
  *   path containment and tenant isolation belong in those operations rather than a CLI-only guard.
  * @file The one composition step that turns "here is an address" into "the plugin is on this
  * machine": {@link fetchAgentPluginArchive} -> `installAgentPlugin`.
  *
- * This is the caller `install.ts` was written for and never had. It adds no extraction, path, or
+ * It adds no extraction, path, or
  * manifest logic of its own — every one of those guarantees still comes from `install.ts`, reached
  * with bytes instead of a URL.
  *

package/dist/lifecycle/install.d.ts

@@ -2,6 +2,9 @@ import type { AgentPluginLayout } from "./layout.js";
 import type { AgentPluginLifecyclePorts } from "./ports.js";
 import type { InstalledAgentPlugin } from "./types.js";
 export type { InstalledAgentPlugin, InstalledAgentPluginSkill } from "./types.js";
+/** One extraction/install failure reason. A caller (an admin route, a future marketplace installer)
+ * branches on `code` rather than parsing `message` — this codebase's own convention
+ * (`PluginLoadError.reason` in `plugin-runtime/loader.ts` is the direct precedent). */
 export type AgentPluginInstallErrorCode = "ARCHIVE_TOO_LARGE" | "DIGEST_MISMATCH" | "TOO_MANY_ENTRIES" | "UNSAFE_ENTRY_PATH" | "SYMLINK_ENTRY_REJECTED" | "UNSUPPORTED_ENTRY_KIND" | "DUPLICATE_ENTRY" | "FILE_TOO_LARGE" | "DECOMPRESSION_BOMB" | "TOTAL_SIZE_EXCEEDED" | "MANIFEST_MISSING" | "MANIFEST_INVALID" | "PUBLISH_FAILED";
 export declare class AgentPluginInstallError extends Error {
     readonly code: AgentPluginInstallErrorCode;
@@ -12,9 +15,14 @@ export declare class AgentPluginInstallError extends Error {
         cause?: unknown;
     });
 }
+/** One archive entry. A symlink is modeled as its OWN kind rather than folded into "file" — the
+ * zip-slip research this module's header cites is explicit that the symlink-entry vector is
+ * distinct from the lexical-traversal one, and the two need independent tests and independent
+ * handling (see the "symlink entries are rejected outright" rule below). */
 export type AgentPluginArchiveEntry = {
     readonly kind: "file";
     readonly entryPath: string;
+    /** The archive format's own claimed size. Never trusted alone — see `DECOMPRESSION_BOMB`. */
     readonly declaredSize?: (number) | undefined;
     readonly executable?: (boolean) | undefined;
     readonly openReadStream: (required: Record<string, never>) => AsyncIterable<Uint8Array>;
@@ -30,6 +38,7 @@ export type AgentPluginArchiveEntry = {
  * `entries` must be a pure function of the archive bytes: an install iterates it twice, once to
  * check entry-count limits from metadata alone and once to extract.
  */
+/** `entries` is a pure function of archive bytes: metadata preflight and extraction iterate it twice. */
 export interface AgentPluginArchiveReaderPort {
     entries(required: {
         readonly archive: Uint8Array;
@@ -37,16 +46,62 @@ export interface AgentPluginArchiveReaderPort {
 }
 export interface InstallAgentPluginRequired {
     readonly archive: Uint8Array;
+    /** Lowercase hex SHA-256 the caller expects `archive` to hash to — a real marketplace flow would
+     * supply this from the server's own metadata; verified here, never trusted from the archive
+     * itself. */
     readonly expectedSha256: string;
     readonly archiveReader: AgentPluginArchiveReaderPort;
+    /**
+     * SECURITY (2026-08-13, security pass Finding 2 — tenant isolation, `ADS-memory/reports/security/
+     * 2026-08-13-post-session-security-pass.md`): this field used to be an already-resolved
+     * `AgentPluginWorkspaceLayout` (`{ root, packages, staging, pluginDataDir }`) — a plain interface
+     * of four independently-typed string/function fields with no tag identifying which workspace it
+     * came from. Nothing stopped a caller from hand-assembling one from two DIFFERENT real
+     * `forWorkspace()` results (wrong variable capture, a stale cached layout, a future code path that
+     * builds one by hand instead of calling `forWorkspace`) — such a value type-checked identically to
+     * a correctly-resolved one, and `installAgentPlugin` published into whatever `packages`/`staging`
+     * it was handed with no consistency check. Proven at the unit level in `install.unit.test.ts`
+     * (a layout stitching workspace A's `root`/`pluginDataDir` onto workspace B's real `packages`/
+     * `staging` published into workspace B's real, on-disk store with no error).
+     *
+     * The fix: `installAgentPlugin` no longer accepts a pre-resolved workspace layout as input AT ALL.
+     * It takes the RAW MATERIALS instead — the INSTANCE-level layout (`resolveAgentPluginLayout()`,
+     * carries no workspace-scoped path of its own) plus one `workspaceId` — and calls
+     * `layout.forWorkspace(workspaceId)` itself, exactly once, internally. There is no longer any
+     * `AgentPluginWorkspaceLayout`-shaped parameter here for a caller to stitch fields into: the one
+     * and only path from these two inputs to `packages`/`staging`/`pluginDataDir` is the real
+     * `forWorkspace()` closure, called atomically, so the four resulting paths can never disagree with
+     * each other about which workspace they belong to. Passing a hand-built `{ packages, staging, ... }`
+     * literal where this field is expected is now a compile-time type error, not a runtime hazard.
+     *
+     * `workspaceId` must still come from the authenticated principal's own request context, never
+     * derived from `layout` itself (a hand-built or malicious `AgentPluginLayout` could fake a
+     * `forWorkspace` implementation identically) — that half of the guarantee is a caller obligation
+     * this type cannot enforce, the same way `archiveReader` above is a fully caller-trusted port. What
+     * IS closed is the specific, demonstrated bug class: stitching or hand-assembling an
+     * already-resolved workspace layout from parts.
+     */
     readonly layout: AgentPluginLayout;
+    /** The workspace this install is for. Combined with {@link layout} via `layout.forWorkspace(workspaceId)`
+     * — see the SECURITY note on {@link layout} above. */
     readonly workspaceId: string;
 }
-export type InstallAgentPluginOptional = {};
+export interface InstallAgentPluginOptional {
+    /** Full bounded extraction/validation in staging, with no package or memory publication. */
+    readonly previewOnly?: boolean;
+    /** Host policy transaction inside the per-plugin lock after validation. Call publish exactly
+     * once to install; returning an existing package without calling it is a deduplicated no-op. */
+    /** Host policy transaction, called inside the existing per-plugin lock after validation.
+     * It must invoke publish exactly once to install. Shared lifecycle counterpart is in chat-tools.jini.patch. */
+    readonly publishGuard?: (required: {
+        readonly plugin: InstalledAgentPlugin;
+        readonly publish: () => Promise<InstalledAgentPlugin>;
+    }, optional: Record<string, never>) => Promise<InstalledAgentPlugin>;
+}
 /** Internal composition; one state/queue instance per injected host context. */
 export declare function createInstallModule(ports: AgentPluginLifecyclePorts): {
     maxAgentPluginInstallArchiveBytes: () => number;
-    installAgentPlugin: (required: InstallAgentPluginRequired, _optional?: InstallAgentPluginOptional) => Promise<InstalledAgentPlugin>;
+    installAgentPlugin: (required: InstallAgentPluginRequired, optional?: InstallAgentPluginOptional) => Promise<InstalledAgentPlugin>;
     indexInstalledRoot: (packageRoot: string, archiveDigest: string) => Promise<InstalledAgentPlugin>;
 };
 //# sourceMappingURL=install.d.ts.map

package/dist/lifecycle/install.js

@@ -1,9 +1,79 @@
+/**
+ * @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 {
@@ -33,11 +103,32 @@ function buildModule(ports) {
         maxFileBytes: 16 * 1024 * 1024,
         maxTotalExtractedBytes: 64 * 1024 * 1024,
     };
+    /** 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 +148,60 @@ function buildModule(ports) {
         try {
             const executablePaths = await extractEntries(archiveReader.entries({ archive }), extractionRoot);
             const indexed = await indexInstalledRoot(extractionRoot, digest);
+            if (optional.previewOnly)
+                return indexed;
             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 };
+                    // 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.
+                    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))
+                            return indexInstalledRoot(finalRoot, digest);
+                        await publish(extractionRoot, finalRoot);
+                        await freezeTree(finalRoot, executablePaths);
+                        /** Absolute, read-only (frozen) path to the extracted package root. */
+                        return { ...indexed, packageRoot: finalRoot };
+                    };
+                    return optional.publishGuard ? optional.publishGuard({ plugin: indexed, publish: publishPackage }, {}) : publishPackage();
                 } });
         }
         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 +210,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 +221,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 +266,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 +279,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 +296,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 +327,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");
@@ -225,22 +392,47 @@ 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,
             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 +447,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 +465,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/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,5 +1,4 @@
 /**
- * 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.
@@ -11,8 +10,7 @@
  * 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):
+ * Pinned v1.0.0 rules from agent-plugins.org/specification:
  * - `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`.
@@ -23,12 +21,8 @@
  *   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):
+ * - Each server entry MUST carry a `type` discriminator matching one of three CLOSED variants.
+ *   Launching requires the actual transport config, not just a server 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).

package/dist/lifecycle/manifest.js

@@ -1,5 +1,4 @@
 /**
- * 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.
@@ -11,8 +10,7 @@
  * 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):
+ * Pinned v1.0.0 rules from agent-plugins.org/specification:
  * - `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`.
@@ -23,12 +21,8 @@
  *   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):
+ * - Each server entry MUST carry a `type` discriminator matching one of three CLOSED variants.
+ *   Launching requires the actual transport config, not just a server 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).
@@ -61,8 +55,7 @@
 export { validatePluginManifest, validateMcpManifest } from '../manifest.js';
 /**
  * The one plugin.json schema version this loader understands. A manifest declaring any other
- * value is rejected outright (C2 in the debate: "the standard is a Working Draft; the loader pins
- * v1 and must survive spec churn") rather than guessed at.
+ * value is rejected outright rather than guessed at: pinning the grammar must survive spec churn.
  */
 const PLUGIN_SCHEMA_1_0_0 = "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json";
 const MCP_SCHEMA_1_0_0 = "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json";