@jini-ai/agent-plugins 0.4.6 → 0.4.7

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.4.7 — 2026-10-15 — folder uploads share one ZIP encoder
+
+- New `./folder-zip` (universal): `zipFolderFiles()`, the binary-safe stored-mode folder encoder,
+  moved here from Tovu's admin so browser and server folder installs pack identically.
+- New `./folder-zip/node`: `zipLocalFolder()` reads a local folder into that same encoder. Refuses
+  symlinks and special files, bounds entries (4096) and bytes before reading, and sorts paths so the
+  same folder always packs to the same digest.
+- The bundled `ui-ux-design/plugin.json` declares its version (abb0009e).
+
 ## 0.4.6 — 2026-10-13 — skills' supporting files are readable
 
 - New `createSkillFileReader()` and lifecycle `readInstalledSkillFile()`: read `SKILL.md` or a

package/README.md

@@ -106,6 +106,8 @@ Catalog format) that this package does not implement.
 | `./lifecycle` | node | Host-injected installation, activation, locks, digests, bundles, trusted files, reference resolution, ranking and MCP provisioning helpers. |
 | `./lifecycle/node` | node | `createNodeAgentPluginEffects({})` opt-in native effects. |
 | `./lifecycle/yauzl` | node | `createYauzlAgentPluginArchiveReader({ yauzl })`; the host supplies the optional peer library. |
+| `./folder-zip` | universal | `zipFolderFiles({ files, maxBytes })`: packs picked folder `File`s into one stored-mode, binary-safe `.zip` `File` (the admin "Upload a folder" encoder). |
+| `./folder-zip/node` | node | `zipLocalFolder({ path, maxBytes })`: the same encoder over a local folder; refuses symlinks/special files, bounds entries and bytes. |
 | `./ui-ux-design/*` | — | Raw files of the bundled `ui-ux-design` plugin — static JSON/Markdown, not run through the TS build. |
 
 The universal root handles structural validation. The separate Node lifecycle entry implements

package/dist/folder-zip-node.d.ts

@@ -0,0 +1,11 @@
+/** Reads a local folder into the browser upload encoder. Refuses links/special files and bounds
+ * entries and bytes before allocation; the resulting ZIP still requires the install validator.
+ * @throws {FolderZipError} Empty, unreadable, linked, or over-limit folders.
+ * @complexity O(e log e + b) time for e entries and b bytes; O(e + b) space,
+ * bounded to 4096 entries and maxBytes. No network I/O.
+ */
+export declare function zipLocalFolder(required: {
+    path: string;
+    maxBytes: number;
+}, _optional?: Record<string, never>): Promise<Uint8Array>;
+//# sourceMappingURL=folder-zip-node.d.ts.map

package/dist/folder-zip-node.js

@@ -0,0 +1,74 @@
+import * as fs from "node:fs/promises";
+import { constants } from "node:fs";
+import path from "node:path";
+import { FOLDER_MAX_FILES, FOLDER_UNREADABLE, FolderZipError, zipFolderFiles } from "./folder-zip.js";
+/** Reads a local folder into the browser upload encoder. Refuses links/special files and bounds
+ * entries and bytes before allocation; the resulting ZIP still requires the install validator.
+ * @throws {FolderZipError} Empty, unreadable, linked, or over-limit folders.
+ * @complexity O(e log e + b) time for e entries and b bytes; O(e + b) space,
+ * bounded to 4096 entries and maxBytes. No network I/O.
+ */
+export async function zipLocalFolder(required, _optional = {}) {
+    const files = [];
+    let entries = 0;
+    let total = 0;
+    try {
+        const root = await fs.realpath(required.path);
+        const pending = [root];
+        while (pending.length) {
+            const directory = pending.pop();
+            if (!(await fs.lstat(directory)).isDirectory() || await fs.realpath(directory) !== directory)
+                throw new FolderZipError("unreadable", FOLDER_UNREADABLE);
+            const handle = await fs.opendir(directory);
+            for await (const entry of handle) {
+                if (++entries > FOLDER_MAX_FILES)
+                    throw new FolderZipError("too-many", `More than ${FOLDER_MAX_FILES} entries.`);
+                const filename = path.join(directory, entry.name);
+                if (entry.isDirectory()) {
+                    pending.push(filename);
+                    continue;
+                }
+                if (!entry.isFile())
+                    throw new FolderZipError("unreadable", FOLDER_UNREADABLE);
+                if (await fs.realpath(filename) !== filename)
+                    throw new FolderZipError("unreadable", FOLDER_UNREADABLE);
+                // O_NOFOLLOW refuses a file replaced with a symlink between enumeration and opening.
+                const file = await fs.open(filename, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+                try {
+                    const info = await file.stat();
+                    if (!info.isFile())
+                        throw new FolderZipError("unreadable", FOLDER_UNREADABLE);
+                    total += info.size;
+                    if (total > required.maxBytes)
+                        throw new FolderZipError("too-large", "Folder is over the upload limit.");
+                    // One extra byte detects growth without an unbounded readFile allocation.
+                    const bytes = Buffer.alloc(info.size + 1);
+                    let length = 0;
+                    while (length < bytes.length) {
+                        const read = await file.read(bytes, length, bytes.length - length, null);
+                        if (read.bytesRead === 0)
+                            break;
+                        length += read.bytesRead;
+                    }
+                    if (length !== info.size)
+                        throw new FolderZipError("unreadable", FOLDER_UNREADABLE);
+                    const picked = new File([new Uint8Array(bytes.subarray(0, length))], entry.name);
+                    Object.defineProperty(picked, "webkitRelativePath", { value: `folder/${path.relative(root, filename).split(path.sep).join("/")}` });
+                    files.push(picked);
+                }
+                finally {
+                    await file.close();
+                }
+            }
+        }
+        // Stable order gives repeat local-folder installs identical ZIP digests.
+        files.sort((a, b) => a.webkitRelativePath < b.webkitRelativePath ? -1 : a.webkitRelativePath > b.webkitRelativePath ? 1 : 0);
+        return new Uint8Array(await (await zipFolderFiles({ files, maxBytes: required.maxBytes })).arrayBuffer());
+    }
+    catch (error) {
+        if (error instanceof FolderZipError)
+            throw error;
+        throw new FolderZipError("unreadable", FOLDER_UNREADABLE);
+    }
+}
+//# sourceMappingURL=folder-zip-node.js.map

package/dist/folder-zip.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @file Packs a folder the operator picked (`<input type=file webkitdirectory>`) into one `.zip`
+ * `File`, so "Upload a folder" travels the exact path a `.zip` upload does: same size limit, same
+ * server-side archive checks, same Preview trust review. The install routes only take
+ * `application/zip`, so zipping here keeps one server path instead of adding a second upload format.
+ *
+ * Stored mode (no compression): the upload limit is on the archive, and a plugin folder is small
+ * text, so deflate would add a dependency for little gain. `@jini-ai/ui` has a stored-mode
+ * `buildZip`, but it is text-only (it would corrupt an image) and not exported, so this is the
+ * binary-safe twin, extracted to Jini so browser and local-folder uploads use the same encoder.
+ */
+/** Refusals, as dictionary keys the caller translates. */
+export declare const FOLDER_EMPTY = "That folder is empty.";
+export declare const FOLDER_UNREADABLE = "Could not read that folder. Try again.";
+/** The archive readers' entry cap (`install-archive.ts`, the Agent Plugins reader): refused here
+ *  before any bytes are read. */
+export declare const FOLDER_MAX_FILES = 4096;
+export declare class FolderZipError extends Error {
+    readonly reason: "empty" | "too-large" | "too-many" | "unreadable";
+    constructor(reason: "empty" | "too-large" | "too-many" | "unreadable", message: string);
+}
+/** @complexity O(n) in the byte count. */
+export declare function crc32(bytes: Uint8Array): number;
+/**
+ * Zips the files of one picked folder.
+ *
+ * @param required.files - Every file the folder picker returned.
+ * @param required.maxBytes - The upload limit; the folder's raw size alone over it is refused before
+ *   reading, and the finished zip is checked again (headers add a little).
+ * @returns `<folder>.zip`, typed `application/zip`.
+ * @throws {FolderZipError} empty folder, too many files, too large, or a file that could not be read.
+ * @complexity O(total bytes).
+ */
+export declare function zipFolderFiles(required: {
+    files: readonly File[];
+    maxBytes: number;
+}, _optional?: Record<string, never>): Promise<File>;
+//# sourceMappingURL=folder-zip.d.ts.map

package/dist/folder-zip.js

@@ -0,0 +1,132 @@
+/**
+ * @file Packs a folder the operator picked (`<input type=file webkitdirectory>`) into one `.zip`
+ * `File`, so "Upload a folder" travels the exact path a `.zip` upload does: same size limit, same
+ * server-side archive checks, same Preview trust review. The install routes only take
+ * `application/zip`, so zipping here keeps one server path instead of adding a second upload format.
+ *
+ * Stored mode (no compression): the upload limit is on the archive, and a plugin folder is small
+ * text, so deflate would add a dependency for little gain. `@jini-ai/ui` has a stored-mode
+ * `buildZip`, but it is text-only (it would corrupt an image) and not exported, so this is the
+ * binary-safe twin, extracted to Jini so browser and local-folder uploads use the same encoder.
+ */
+/** Refusals, as dictionary keys the caller translates. */
+export const FOLDER_EMPTY = "That folder is empty.";
+export const FOLDER_UNREADABLE = "Could not read that folder. Try again.";
+/** The archive readers' entry cap (`install-archive.ts`, the Agent Plugins reader): refused here
+ *  before any bytes are read. */
+export const FOLDER_MAX_FILES = 4096;
+export class FolderZipError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+    }
+}
+/** 1980-01-01, the earliest DOS date: a fixed stamp, so the same folder always zips to the same
+ *  bytes (an all-zero date is month 0, which some readers refuse). */
+const DOS_DATE_1980 = (1 << 5) | 1;
+const CRC_TABLE = (() => {
+    const table = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        table[n] = c >>> 0;
+    }
+    return table;
+})();
+/** @complexity O(n) in the byte count. */
+export function crc32(bytes) {
+    let c = 0xffffffff;
+    for (let i = 0; i < bytes.length; i++)
+        c = CRC_TABLE[(c ^ bytes[i]) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+}
+/** A picked file's path inside the picked folder: `webkitRelativePath` minus the folder's own name,
+ *  so the package's files sit at the top of the zip — what a server-path install of that same
+ *  folder reads, and where both install routes look for the manifest. */
+function entryPath(file) {
+    const relative = (file.webkitRelativePath || file.name).replaceAll("\\", "/");
+    const slash = relative.indexOf("/");
+    return slash < 0 ? { folder: "", path: relative } : { folder: relative.slice(0, slash), path: relative.slice(slash + 1) };
+}
+/**
+ * Zips the files of one picked folder.
+ *
+ * @param required.files - Every file the folder picker returned.
+ * @param required.maxBytes - The upload limit; the folder's raw size alone over it is refused before
+ *   reading, and the finished zip is checked again (headers add a little).
+ * @returns `<folder>.zip`, typed `application/zip`.
+ * @throws {FolderZipError} empty folder, too many files, too large, or a file that could not be read.
+ * @complexity O(total bytes).
+ */
+export async function zipFolderFiles(required, _optional = {}) {
+    const { files, maxBytes } = required;
+    if (files.length === 0)
+        throw new FolderZipError("empty", FOLDER_EMPTY);
+    if (files.length > FOLDER_MAX_FILES)
+        throw new FolderZipError("too-many", `More than ${FOLDER_MAX_FILES} files.`);
+    if (files.reduce((sum, file) => sum + file.size, 0) > maxBytes)
+        throw new FolderZipError("too-large", "Folder is over the upload limit.");
+    const encoder = new TextEncoder();
+    const chunks = [];
+    const central = [];
+    let offset = 0;
+    let folder = "";
+    for (const file of files) {
+        const entry = entryPath(file);
+        folder ||= entry.folder;
+        let data;
+        try {
+            data = new Uint8Array(await file.arrayBuffer());
+        }
+        catch {
+            throw new FolderZipError("unreadable", FOLDER_UNREADABLE);
+        }
+        const name = encoder.encode(entry.path);
+        const crc = crc32(data);
+        // Bit 11: the name is UTF-8, so a reader never decodes it as CP437.
+        const flags = name.some((b) => b > 0x7f) ? 0x0800 : 0;
+        const local = new Uint8Array(30 + name.length);
+        const lv = new DataView(local.buffer);
+        lv.setUint32(0, 0x04034b50, true);
+        lv.setUint16(4, 20, true);
+        lv.setUint16(6, flags, true);
+        lv.setUint16(12, DOS_DATE_1980, true);
+        lv.setUint32(14, crc, true);
+        lv.setUint32(18, data.length, true);
+        lv.setUint32(22, data.length, true);
+        lv.setUint16(26, name.length, true);
+        local.set(name, 30);
+        // Version-made-by 20 (MS-DOS, external attributes 0): a plain file to every reader, so the
+        // server's Unix special-entry guard never sees a mode to refuse.
+        const header = new Uint8Array(46 + name.length);
+        const cv = new DataView(header.buffer);
+        cv.setUint32(0, 0x02014b50, true);
+        cv.setUint16(4, 20, true);
+        cv.setUint16(6, 20, true);
+        cv.setUint16(8, flags, true);
+        cv.setUint16(14, DOS_DATE_1980, true);
+        cv.setUint32(16, crc, true);
+        cv.setUint32(20, data.length, true);
+        cv.setUint32(24, data.length, true);
+        cv.setUint16(28, name.length, true);
+        cv.setUint32(42, offset, true);
+        header.set(name, 46);
+        chunks.push(local, data);
+        central.push(header);
+        offset += local.length + data.length;
+    }
+    const centralSize = central.reduce((sum, part) => sum + part.length, 0);
+    const end = new Uint8Array(22);
+    const ev = new DataView(end.buffer);
+    ev.setUint32(0, 0x06054b50, true);
+    ev.setUint16(8, files.length, true);
+    ev.setUint16(10, files.length, true);
+    ev.setUint32(12, centralSize, true);
+    ev.setUint32(16, offset, true);
+    if (offset + centralSize + end.length > maxBytes)
+        throw new FolderZipError("too-large", "Folder is over the upload limit.");
+    return new File([...chunks, ...central, end], `${folder || "folder"}.zip`, { type: "application/zip" });
+}
+//# sourceMappingURL=folder-zip.js.map

package/dist/lifecycle/install-errors.d.ts

@@ -0,0 +1,14 @@
+/** 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 = "PLUGIN_ID_CONFLICT" | "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;
+    constructor({ code, message }: {
+        readonly code: AgentPluginInstallErrorCode;
+        readonly message: string;
+    }, options?: {
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=install-errors.d.ts.map

package/dist/lifecycle/install-errors.js

@@ -0,0 +1,9 @@
+export class AgentPluginInstallError extends Error {
+    code;
+    constructor({ code, message }, options = {}) {
+        super(message, options);
+        this.name = "AgentPluginInstallError";
+        this.code = code;
+    }
+}
+//# sourceMappingURL=install-errors.js.map

package/dist/lifecycle/install.d.ts

@@ -2,19 +2,8 @@ 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 = "PLUGIN_ID_CONFLICT" | "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;
-    constructor({ code, message }: {
-        readonly code: AgentPluginInstallErrorCode;
-        readonly message: string;
-    }, options?: {
-        cause?: unknown;
-    });
-}
+export { AgentPluginInstallError } from "./install-errors.js";
+export type { AgentPluginInstallErrorCode } from "./install-errors.js";
 /** 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

package/dist/lifecycle/install.js

@@ -1,5 +1,7 @@
 import { listInstalledPackageRoots } from "./installed-package-roots.js";
 import { createUninstallModule } from "./uninstall.js";
+import { AgentPluginInstallError } from "./install-errors.js";
+import { createInstalledPackageIndex } from "./installed-package-index.js";
 import { readPluginIdentity, assertPluginIdentityAvailable } from "@jini-ai/core/plugin-directory";
 /**
  * @file `installAgentPlugin()` — content-addressed, adversarially-hardened extraction of one Agent
@@ -60,33 +62,14 @@ import { readPluginIdentity, assertPluginIdentityAvailable } from "@jini-ai/core
  * (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 { readAgentPluginExtension, parseAgentPluginManifest as parseAgentPluginManifestValue } from "./manifest.js";
 import { PackagePathViolation } from "./package-paths.js";
 import { createPackagePathsModule } from "./package-paths.js";
-export class AgentPluginInstallError extends Error {
-    code;
-    constructor({ code, message }, options = {}) {
-        super(message, options);
-        this.name = "AgentPluginInstallError";
-        this.code = code;
-    }
-}
+export { AgentPluginInstallError } from "./install-errors.js";
 function buildModule(ports) {
     const persistentState = createPersistentStateModule(ports);
     const chmod = ports.filesystem.chmod.bind(ports.filesystem);
@@ -98,7 +81,8 @@ 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 }, { identityNamespace: ports.extensionNamespace });
+    const index = createInstalledPackageIndex({ ports });
+    const indexInstalledRoot = (packageRoot, archiveDigest) => index.indexInstalledRoot({ packageRoot, archiveDigest });
     const { assertContainedOnDisk, normalizePackageEntryPath } = createPackagePathsModule(ports);
     const LIMITS = {
         maxArchiveBytes: 32 * 1024 * 1024,
@@ -145,7 +129,6 @@ function buildModule(ports) {
      */
     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)
@@ -400,107 +383,6 @@ function buildModule(ports) {
         }
         return totalBytes;
     }
-    /** 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");
-        }
-        catch (error) {
-            if (isErrnoException(error) && error.code === "ENOENT") {
-                throw new AgentPluginInstallError({ code: "MANIFEST_MISSING", message: "the archive does not contain a plugin.json at its root" });
-            }
-            throw error;
-        }
-        let manifestValue;
-        try {
-            manifestValue = JSON.parse(manifestRaw);
-        }
-        catch (error) {
-            throw new AgentPluginInstallError({ code: "MANIFEST_INVALID", message: "plugin.json is not valid JSON" }, { cause: error });
-        }
-        const parsed = parseAgentPluginManifest(manifestValue);
-        if (!parsed.ok) {
-            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 })) {
-                const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
-                if (entry.isDirectory()) {
-                    await walk(path.join(absolute, entry.name), relative);
-                }
-                else if (entry.isFile()) {
-                    files.push(relative);
-                    const match = relative.match(/^skills\/([^/]+)\/SKILL\.md$/);
-                    if (match)
-                        skills.push({ name: match[1], skillPath: relative });
-                }
-                // Anything that is neither a directory nor a regular file (a symlink somehow already present,
-                // a device node) is skipped rather than indexed — extraction itself never creates one, so
-                // encountering one here would mean the filesystem changed out from under an already-published,
-                // 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,
-            ...( /**
-         * `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

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

@@ -0,0 +1,15 @@
+import type { AgentPluginLifecyclePorts } from "./ports.js";
+import type { InstalledAgentPlugin } from "./types.js";
+/** Indexes manifests and files with the same injected effects used by installation and resolution.
+ * @complexity O(f) reads/walk work for f package files; no mutation or executable imports. */
+export declare function createInstalledPackageIndex(required: {
+    readonly ports: AgentPluginLifecyclePorts;
+}, _optional?: Record<string, never>): {
+    indexInstalledRoot: ({ packageRoot, archiveDigest }: {
+        readonly packageRoot: string;
+        /** 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`). */
+        readonly archiveDigest: string;
+    }, _optional?: Record<string, never>) => Promise<InstalledAgentPlugin>;
+};
+//# sourceMappingURL=installed-package-index.d.ts.map

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

@@ -0,0 +1,116 @@
+/** Read-side owner of installed package metadata; never constructs a mutation lifecycle. */
+import path from "node:path";
+import { AgentPluginInstallError } from "./install-errors.js";
+import { readAgentPluginExtension, parseAgentPluginManifest as parseAgentPluginManifestValue } from "./manifest.js";
+/** Indexes manifests and files with the same injected effects used by installation and resolution.
+ * @complexity O(f) reads/walk work for f package files; no mutation or executable imports. */
+export function createInstalledPackageIndex(required, _optional = {}) {
+    const { ports } = required;
+    const readFile = ports.filesystem.readFile.bind(ports.filesystem);
+    const readdir = ports.filesystem.readdir.bind(ports.filesystem);
+    const parseAgentPluginManifest = (value) => parseAgentPluginManifestValue({ value }, { identityNamespace: ports.extensionNamespace });
+    /** Cosmetic fields are trimmed and capped rather than invalidating the package. The cap stops
+     * a hostile package flooding an admin row. Malformed values fall back because these fields are
+     * cosmetic: callers title-case the id and show the spec description when these keys are absent.
+     * 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, archiveDigest }, _optional = {}) {
+        let manifestRaw;
+        try {
+            manifestRaw = await readFile(path.join(packageRoot, "plugin.json"), "utf8");
+        }
+        catch (error) {
+            if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT") {
+                throw new AgentPluginInstallError({ code: "MANIFEST_MISSING", message: "the archive does not contain a plugin.json at its root" });
+            }
+            throw error;
+        }
+        let manifestValue;
+        try {
+            manifestValue = JSON.parse(manifestRaw);
+        }
+        catch (error) {
+            throw new AgentPluginInstallError({ code: "MANIFEST_INVALID", message: "plugin.json is not valid JSON" }, { cause: error });
+        }
+        const parsed = parseAgentPluginManifest(manifestValue);
+        if (!parsed.ok) {
+            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 })) {
+                const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+                if (entry.isDirectory()) {
+                    await walk(path.join(absolute, entry.name), relative);
+                }
+                else if (entry.isFile()) {
+                    files.push(relative);
+                    const match = relative.match(/^skills\/([^/]+)\/SKILL\.md$/);
+                    if (match)
+                        skills.push({ name: match[1], skillPath: relative });
+                }
+                // Anything that is neither a directory nor a regular file (a symlink somehow already present,
+                // a device node) is skipped rather than indexed — extraction itself never creates one, so
+                // encountering one here would mean the filesystem changed out from under an already-published,
+                // 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,
+            ...( /**
+         * `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)),
+        };
+    }
+    return { indexInstalledRoot };
+}
+//# sourceMappingURL=installed-package-index.js.map

package/dist/lifecycle/manifest.d.ts

@@ -30,6 +30,7 @@ export type ParseAgentPluginManifestResult = {
 };
 /**
  * Validates an already-`JSON.parse`d `plugin.json` value against the 1.0.0/1.1.0 grammar.
+ * Hosts inject identityNamespace; the default retains the existing plugin extension format.
  *
  * @throws Nothing — every failure is reported via the returned `errors`, matching this codebase's
  * own convention for expected validation outcomes (`plugin-runtime/manifest.ts`,