@jini-ai/agent-plugins 0.4.5 → 0.4.7

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # 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
+  supporting text file (`references/…`, `examples/…`, …) relative to one skill folder, with a sorted
+  `files` inventory. Refused: `..`, absolute or drive paths, symlinks resolving outside the skill
+  (including sibling skills), non-text extensions, binary or invalid UTF-8, files over 256 KiB.
+  Refusals return a note naming the valid files; no host path ever appears in output.
+- Run-start injection lists supporting files relative to the skill folder instead of absolute host
+  paths, and points at the plugin tool's `file` argument. Activation-read refusals no longer echo
+  the native error (which could name a host path).
+
 ## 0.4.5 — 2026-10-12 — retirement waits for usable successors
 
 - `retireBundledAgentPlugins()` (and so the boot seeder) keeps a retired bundled plugin until EVERY

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/capability-projection.d.ts

@@ -1,10 +1,17 @@
 /** Extracted from the host plugin lifecycle. Effects are supplied per host context. */
 import type { McpServerConfig } from "./manifest.js";
 import type { AgentPluginLifecyclePorts } from "./ports.js";
+import { type SkillFileResult } from "./skill-file-reader.js";
 /** Internal composition; one state/queue instance per injected host context. */
 export declare function createCapabilityProjectionModule(ports: AgentPluginLifecyclePorts): {
     classifyAgentPluginMcpServerTrust: (server: Pick<McpServerConfig, "type">) => "auto-admit" | "requires-confirmation";
     readInstalledSkillMarkdown: (packageRoot: string, skillPath: string) => Promise<string>;
+    readInstalledSkillFile: ({ packageRoot, skillPath }: {
+        readonly packageRoot: string;
+        readonly skillPath: string;
+    }, options?: {
+        readonly file?: string;
+    }) => Promise<SkillFileResult>;
     readInstalledMcpServerIds: (packageRoot: string) => Promise<readonly string[]>;
     readInstalledMcpServers: (packageRoot: string) => Promise<Readonly<Record<string, McpServerConfig>>>;
 };

package/dist/lifecycle/capability-projection.js

@@ -1,5 +1,7 @@
 import { parseAgentPluginMcpConfig as parseAgentPluginMcpConfigValue } from "./manifest.js";
 import { createPackagePathsModule } from "./package-paths.js";
+import path from "node:path";
+import { createSkillFileReader } from "./skill-file-reader.js";
 function buildModule(ports) {
     const readFile = ports.filesystem.readFile.bind(ports.filesystem);
     const parseAgentPluginMcpConfig = (value, pluginManifest) => parseAgentPluginMcpConfigValue({ value, extensionNamespace: ports.extensionNamespace }, { pluginManifest, readServerMetadata: ports.readServerMetadata });
@@ -11,6 +13,17 @@ function buildModule(ports) {
         const absolute = await assertContainedOnDisk(packageRoot, skillPath);
         return readFile(absolute, "utf8");
     }
+    /** One shared progressive-disclosure read; the install's skillPath, never caller file input,
+     * selects the skill folder. Unknown/refused files produce a recoverable model-facing note. */
+    async function readInstalledSkillFile({ packageRoot, skillPath }, options = {}) {
+        try {
+            const skillRoot = path.dirname(await assertContainedOnDisk(packageRoot, skillPath));
+            return await createSkillFileReader({ skillRoot, filesystem: ports.filesystem }).read({}, options);
+        }
+        catch {
+            return { text: "", files: [], note: "File request refused: the installed skill folder is missing, unreadable, or outside the package. Valid supporting files: (none)." };
+        }
+    }
     async function readInstalledMcpConfig(packageRoot) {
         let raw;
         try {
@@ -45,7 +58,7 @@ function buildModule(ports) {
         const config = await readInstalledMcpConfig(packageRoot);
         return config?.servers ?? {};
     }
-    return { classifyAgentPluginMcpServerTrust, readInstalledSkillMarkdown, readInstalledMcpServerIds, readInstalledMcpServers };
+    return { classifyAgentPluginMcpServerTrust, readInstalledSkillMarkdown, readInstalledSkillFile, readInstalledMcpServerIds, readInstalledMcpServers };
 }
 const instances = new WeakMap();
 /** Internal composition; one state/queue instance per injected host context. */

package/dist/lifecycle/index.d.ts

@@ -6,6 +6,8 @@ import type { InstalledDigestIdentity } from './bundled-digests.js';
 export type { SeededAgentPluginOutcome, SeedBundledAgentPluginsRequired, SeedBundledAgentPluginsResult } from './seed-bundled.js';
 export type { RetireBundledAgentPluginsRequired, RetireBundledAgentPluginsOptional, RetiredAgentPluginOutcome, RetiredAgentPluginSuccessorOutcome } from './retire-bundled.js';
 export * from './ports.js';
+export { createSkillFileReader } from './skill-file-reader.js';
+export type { SkillFileReader, SkillFileResult } from './skill-file-reader.js';
 export * from './layout.js';
 export * from './manifest.js';
 export * from './fetch-archive.js';
@@ -137,6 +139,12 @@ export declare function createAgentPluginLifecycle(required: AgentPluginLifecycl
         readonly packageRoot: string;
         readonly skillPath: string;
     }) => Promise<string>;
+    readInstalledSkillFile: ({ packageRoot, skillPath }: {
+        readonly packageRoot: string;
+        readonly skillPath: string;
+    }, options?: {
+        readonly file?: string;
+    }) => Promise<import("./skill-file-reader.js").SkillFileResult>;
     readInstalledMcpServerIds: (input: {
         readonly packageRoot: string;
     }) => Promise<readonly string[]>;

package/dist/lifecycle/index.js

@@ -16,6 +16,7 @@ import { createTrustedPluginFilesModule } from './trusted-plugin-files.js';
 import { createPluginContributionLoader } from './contribution-loader.js';
 import { createUninstallModule } from './uninstall.js';
 export * from './ports.js';
+export { createSkillFileReader } from './skill-file-reader.js';
 export * from './layout.js';
 export * from './manifest.js';
 export * from './fetch-archive.js';
@@ -89,6 +90,7 @@ export function createAgentPluginLifecycle(required, optional = {}) {
         assertContainedOnDisk: (input) => paths.assertContainedOnDisk(input.packageRoot, input.entryPath),
         classifyAgentPluginMcpServerTrust: (input) => capabilities.classifyAgentPluginMcpServerTrust(input.server),
         readInstalledSkillMarkdown: (input) => capabilities.readInstalledSkillMarkdown(input.packageRoot, input.skillPath),
+        readInstalledSkillFile: capabilities.readInstalledSkillFile,
         readInstalledMcpServerIds: (input) => capabilities.readInstalledMcpServerIds(input.packageRoot),
         readInstalledMcpServers: (input) => capabilities.readInstalledMcpServers(input.packageRoot),
         resolveAgentPluginRefs: (input, optional = {}) => refs.resolveAgentPluginRefs(input.pluginRefIds, input.workspaceLayout, optional.deliveryMode ?? context.deliveryMode),

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`,

package/dist/lifecycle/manifest.js

@@ -150,6 +150,7 @@ function resolveManifestName(raw) {
 }
 /**
  * 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`,

package/dist/lifecycle/package-paths.d.ts

@@ -7,7 +7,7 @@ export declare class PackagePathViolation extends Error {
     }, optional?: ErrorOptions);
 }
 /** Internal composition; one state/queue instance per injected host context. */
-export declare function createPackagePathsModule(ports: AgentPluginLifecyclePorts): {
+export declare function createPackagePathsModule(ports: Pick<AgentPluginLifecyclePorts, "filesystem">): {
     normalizePackageEntryPath: (rawEntryPath: string) => string;
     assertContainedOnDisk: (packageRoot: string, entryPath: string) => Promise<string>;
 };

package/dist/lifecycle/resolve-agent-plugin-refs.d.ts

@@ -1,8 +1,8 @@
 import type { /**
  * How a pinned ref's content reaches the agent.
  *
- * - `inject` — the whole eponymous SKILL.md (~15KB for `ui-ux-design`) plus every other package file
- *   listed by absolute path, in the run's prompt prefix. Today's shipped behaviour, and the default.
+ * - `inject` — the whole eponymous SKILL.md (~15KB for `ui-ux-design`) plus its readable supporting-file inventory
+ *   listed relative to the skill folder, in the run's prompt prefix. Today's shipped behaviour, and the default.
  * - `pointer` — ~400 bytes naming the exact tool call that returns that SAME SKILL.md, and nothing
  *   else. The content is identical; only the delivery differs, which is what makes the two a
  *   controlled comparison rather than two different experiments.

package/dist/lifecycle/resolve-agent-plugin-refs.js

@@ -45,13 +45,12 @@ import { listInstalledPackageRoots, INSTALLED_PLUGIN_DIGEST_PATTERN } from "./in
  * examples, scripts) is supporting material a plugin's own SKILL.md is written to point an agent
  * at when it needs more depth (the Agent Plugins spec's own convention every skill in this package
  * follows). Injecting the FULL package indiscriminately would balloon every run's prompt with
- * pages this specific task usually never needs. Every OTHER file in the resolved package is still
- * listed by absolute path — genuinely `Read`-able by the spawned CLI agent, which runs with real
- * filesystem access unlike a browser-facing preview — so nothing is unreachable, only deferred to
- * an explicit follow-up read.
+ * pages this specific task usually never needs. Readable supporting files are listed relative to
+ * the chosen skill folder and loaded through the same plugin tool used by browser-facing assistants
+ * and CLI agents — supporting content is deferred to an explicit follow-up read.
  *
  * Architectural role:
- * Server-side only (reads `node:fs/promises`, imports `install.ts`'s `indexInstalledRoot`) — never
+ * Server-side only (reads injected filesystem ports through the installed-package index) — never
  * imported into a browser bundle. Returns a discriminated result rather than throwing, so
  * `agent-daemon-server.ts`'s `onStarted` gets one place to branch on success/failure without a
  * second try/catch layer duplicating this module's own error classification.
@@ -61,7 +60,7 @@ import path from "node:path";
 import { createPackagePathsModule } from "./package-paths.js";
 import { createActivationModule } from "./activation.js";
 import { createBundledDigestsModule } from "./bundled-digests.js";
-import { createInstallModule } from "./install.js";
+import { createInstalledPackageIndex } from "./installed-package-index.js";
 import { createCapabilityProjectionModule } from "./capability-projection.js";
 function buildModule(ports) {
     const persistentState = createPersistentStateModule(ports);
@@ -69,8 +68,8 @@ function buildModule(ports) {
     const stat = ports.filesystem.stat.bind(ports.filesystem);
     const { resolveAgentPluginActivation } = createActivationModule(ports);
     const { preferBundledAgentPluginDigests, readBundledAgentPluginDigests } = createBundledDigestsModule(ports);
-    const { indexInstalledRoot } = createInstallModule(ports);
-    const { readInstalledSkillMarkdown } = createCapabilityProjectionModule(ports);
+    const { indexInstalledRoot } = createInstalledPackageIndex({ ports });
+    const { readInstalledSkillFile } = createCapabilityProjectionModule(ports);
     /** Reads the delivery mode for this process. An unset or unrecognised value is `inject` — an A/B
    *  affordance must never be able to change production behaviour by typo. */
     function resolveAgentPluginDeliveryMode() { return ports.deliveryMode; }
@@ -126,8 +125,9 @@ function buildModule(ports) {
         if (verdict.verdict === "active")
             return undefined;
         if (verdict.verdict === "undetermined") {
+            // Native activation-read diagnostics can name the host path; the model needs only the remedy.
             return (`Agent Plugin '${pluginRefId}' was not loaded: this workspace's activation record could not be read, so whether ` +
-                `it is enabled cannot be confirmed (${verdict.reason}). Nothing was injected; repair activations.json and start the run again.`);
+                `it is enabled cannot be confirmed. Nothing was injected; repair activations.json and start the run again.`);
         }
         return (`Agent Plugin '${pluginRefId}' is installed in this workspace but is not enabled — it ships with ${ports.productName} and ` +
             "stays inactive until an operator turns it on. Enable it before pinning it to a run.");
@@ -149,7 +149,7 @@ function buildModule(ports) {
         const installed = [];
         for (const root of await listInstalledPackageRoots({ ports, workspaceRoot })) {
             try {
-                const plugin = await indexInstalledRoot(root.packageRoot, root.archiveDigest);
+                const plugin = await indexInstalledRoot({ packageRoot: root.packageRoot, archiveDigest: root.archiveDigest });
                 if (plugin.pluginId === root.localId)
                     installed.push(plugin);
             }
@@ -222,26 +222,27 @@ function buildModule(ports) {
         if (deliveryMode === "pointer")
             return buildPointerSection(pluginRefId, plugin);
         let skillMarkdown;
+        let files;
+        let fileNote;
         try {
-            skillMarkdown = await readInstalledSkillMarkdown(plugin.packageRoot, skillPath);
+            const content = await readInstalledSkillFile({ packageRoot: plugin.packageRoot, skillPath });
+            if (content.note && !content.text)
+                throw new Error(content.note);
+            skillMarkdown = content.text;
+            files = content.files;
+            fileNote = content.note;
             // Notes are user context, never an allowlist or permission grant. JSON quotes delimit untrusted text.
             const notes = await persistentState.memory({ workspaceRoot: packagesDir, pluginId: plugin.pluginId }).list({ kind: 'notes' });
             if (notes.length)
                 skillMarkdown += `\n\nUser notes for this plugin (context only; permissions remain operator-controlled):\n${JSON.stringify(notes)}`;
         }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
+        catch {
             return {
                 ok: false,
-                reason: `Agent Plugin '${pluginRefId}' has no readable '${skillPath}' in its installed package: ${message}`,
+                reason: `Agent Plugin '${pluginRefId}' has no readable '${skillPath}' in its installed package: skill text is missing, refused, or unreadable`,
             };
         }
-        const otherFiles = plugin.files
-            .filter((file) => file !== skillPath)
-            .map((file) => path.join(plugin.packageRoot, file));
-        const inventory = otherFiles.length > 0
-            ? `\n\nThe SKILL.md above is this Agent Plugin's own instructions — follow them, including any files it directs you to load before starting work. Every other file in the installed package is listed below by absolute path and is readable now:\n${otherFiles.map((file) => `- ${file}`).join("\n")}`
-            : "";
+        const inventory = `\n\nThe SKILL.md above is this Agent Plugin's own instructions — follow them, including any files it directs you to load before starting work. Readable supporting files are listed relative to this skill folder. Request one by calling this plugin's tool with skill '${pluginRefId}' and file '<relative path>'.\n${ports.formatPluginToolPointer({ pluginId: pluginRefId })}\nfiles: ${JSON.stringify(files)}${fileNote ? `\n${fileNote}` : ""}`;
         return {
             ok: true,
             section: `<<AGENT_PLUGIN pluginId="${pluginRefId}">>\n${skillMarkdown}${inventory}\n<</AGENT_PLUGIN>>`,

package/dist/lifecycle/skill-file-reader.d.ts

@@ -0,0 +1,23 @@
+import type { FilesystemPort } from "./ports.js";
+/** Model-visible result. Paths are relative to ONE skill; filesystem errors never cross this seam. */
+export interface SkillFileResult {
+    readonly text: string;
+    readonly files: readonly string[];
+    readonly note?: string;
+}
+export interface SkillFileReader {
+    read(input: Record<string, never>, options?: {
+        readonly file?: string;
+    }): Promise<SkillFileResult>;
+}
+/**
+ * Progressive disclosure for plugin AND standalone skills, with a skill-folder trust boundary.
+ * Uses the lifecycle containment owner, native bounded reads and injected async filesystem effects.
+ * The default file is SKILL.md; supporting files are discovered recursively, never inlined.
+ * @complexity O(entries + readable bytes), bounded by 4096 entries, depth 32 and 256 KiB per file.
+ */
+export declare function createSkillFileReader({ skillRoot, filesystem }: {
+    readonly skillRoot: string;
+    readonly filesystem: FilesystemPort;
+}, _options?: Record<string, never>): SkillFileReader;
+//# sourceMappingURL=skill-file-reader.d.ts.map

package/dist/lifecycle/skill-file-reader.js

@@ -0,0 +1,130 @@
+import { constants } from "node:fs";
+import path from "node:path";
+import { TextDecoder } from "node:util";
+import { createPackagePathsModule } from "./package-paths.js";
+const TEXT_EXTENSIONS = new Set([".md", ".mdx", ".txt", ".json", ".yaml", ".yml", ".ts", ".tsx", ".js", ".jsx", ".css", ".html", ".csv", ".svg", ".py", ".sh"]);
+const MAX_FILE_BYTES = 256 * 1024;
+const MAX_WALK_ENTRIES = 4096;
+const MAX_WALK_DEPTH = 32;
+/**
+ * Progressive disclosure for plugin AND standalone skills, with a skill-folder trust boundary.
+ * Uses the lifecycle containment owner, native bounded reads and injected async filesystem effects.
+ * The default file is SKILL.md; supporting files are discovered recursively, never inlined.
+ * @complexity O(entries + readable bytes), bounded by 4096 entries, depth 32 and 256 KiB per file.
+ */
+export function createSkillFileReader({ skillRoot, filesystem }, _options = {}) {
+    const { assertContainedOnDisk } = createPackagePathsModule({ filesystem });
+    /** Reject traversal even when normalization would leave it inside the folder. */
+    function validateFile(file) {
+        if (!file || file.includes("\0") || file.includes("\\") || path.posix.isAbsolute(file) || /^[a-zA-Z]:/.test(file) || file.split("/").some(segment => segment === "..")) {
+            throw new Error("File request refused: use a path relative to this skill folder, without traversal or absolute paths.");
+        }
+        if (!TEXT_EXTENSIONS.has(path.extname(file).toLowerCase())) {
+            throw new Error("File request refused: only supported text extensions are readable.");
+        }
+    }
+    /** Open the resolved target with no-follow and read at most cap + 1, including growing files. */
+    async function readText(file) {
+        validateFile(file);
+        let absolute;
+        try {
+            absolute = await filesystem.realpath(await assertContainedOnDisk(skillRoot, file));
+            // Recheck the canonical target through the same owner before opening it.
+            const relative = path.relative(await filesystem.realpath(skillRoot), absolute);
+            await assertContainedOnDisk(skillRoot, relative);
+            validateFile(relative.split(path.sep).join("/"));
+        }
+        catch {
+            throw new Error("File request refused: file is missing, unreadable, or resolves outside this skill folder.");
+        }
+        let handle;
+        try {
+            handle = await filesystem.open(absolute, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+            const stat = await handle.stat();
+            if (!stat.isFile())
+                throw new Error("File request refused: only regular text files are readable.");
+            if (stat.size > MAX_FILE_BYTES)
+                throw new Error("File request refused: exceeds the 256 KiB text limit; no content returned.");
+            const buffer = Buffer.alloc(MAX_FILE_BYTES + 1);
+            let length = 0;
+            while (length < buffer.length) {
+                const { bytesRead } = await handle.read(buffer, length, buffer.length - length, null);
+                if (!bytesRead)
+                    break;
+                length += bytesRead;
+            }
+            if (length > MAX_FILE_BYTES)
+                throw new Error("File request refused: exceeds the 256 KiB text limit; no content returned.");
+            const bytes = buffer.subarray(0, length);
+            if (bytes.some(byte => (byte < 32 && byte !== 9 && byte !== 10 && byte !== 13) || byte === 127))
+                throw new Error("File request refused: binary content cannot be read as text.");
+            try {
+                return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+            }
+            catch {
+                throw new Error("File request refused: binary or invalid UTF-8 content cannot be read as text.");
+            }
+        }
+        catch (error) {
+            // Never reflect native errors or caller paths: either can contain an absolute host path.
+            if (error instanceof Error && error.message.startsWith("File request refused:"))
+                throw error;
+            throw new Error("File request refused: file is missing or unreadable.");
+        }
+        finally {
+            await handle?.close().catch(() => { });
+        }
+    }
+    /** Skip directory symlinks (including cycles); contained file symlinks use the same read guard. */
+    async function listFiles() {
+        const files = [];
+        let remaining = MAX_WALK_ENTRIES;
+        let incomplete = false;
+        async function walk(relative, depth) {
+            if (depth > MAX_WALK_DEPTH || remaining <= 0) {
+                incomplete = true;
+                return;
+            }
+            let entries;
+            try {
+                const directory = relative ? await assertContainedOnDisk(skillRoot, relative) : await filesystem.realpath(skillRoot);
+                entries = await filesystem.readdir(directory, { withFileTypes: true });
+            }
+            catch {
+                incomplete = true;
+                return;
+            }
+            for (const entry of entries.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)) {
+                if (remaining-- <= 0) {
+                    incomplete = true;
+                    break;
+                }
+                const file = relative ? `${relative}/${entry.name}` : entry.name;
+                if (entry.isDirectory())
+                    await walk(file, depth + 1);
+                else if (file !== "SKILL.md" && (entry.isFile() || entry.isSymbolicLink())) {
+                    try {
+                        await readText(file);
+                        files.push(file);
+                    }
+                    catch { /* Refused files must not be advertised as readable. */ }
+                }
+            }
+        }
+        await walk("", 0);
+        return { files: files.sort(), ...(incomplete ? { note: "Supporting-file inventory is incomplete: traversal limit reached or a directory is unreadable." } : {}) };
+    }
+    return {
+        async read(_input, options = {}) {
+            const listing = await listFiles();
+            try {
+                return { ...listing, text: await readText(options.file ?? "SKILL.md") };
+            }
+            catch (error) {
+                const refusal = error instanceof Error ? error.message : "File request refused.";
+                return { files: listing.files, text: "", note: [refusal, `Valid supporting files: ${listing.files.join(", ") || "(none)"}. Omit file to request SKILL.md.`, listing.note].filter(Boolean).join(" ") };
+            }
+        },
+    };
+}
+//# sourceMappingURL=skill-file-reader.js.map

package/dist/manifest.d.ts

@@ -58,7 +58,8 @@ export interface McpManifest {
     readonly mcpServers: Readonly<Record<string, McpServerEntry>>;
 }
 export declare function isMcpManifest(value: unknown): value is McpManifest;
-/** Object-argument facade for the legacy structural validator. */
+/** Object-argument facade for the legacy structural validator.
+ * Hosts inject identityNamespace; the default retains the existing plugin extension format. */
 export declare function validatePluginManifest(required: {
     readonly value: unknown;
 }, optional?: {

package/dist/manifest.js

@@ -28,7 +28,8 @@ export function isMcpManifest(value) {
     const servers = value.mcpServers;
     return typeof servers === 'object' && servers !== null && !Array.isArray(servers);
 }
-/** Object-argument facade for the legacy structural validator. */
+/** Object-argument facade for the legacy structural validator.
+ * Hosts inject identityNamespace; the default retains the existing plugin extension format. */
 export function validatePluginManifest(required, optional = {}) {
     return isPluginManifest(required.value) && validatePluginIdentity({ manifest: required.value, namespace: optional.identityNamespace ?? "tovu" }).errors.length === 0;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/agent-plugins",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "description": "Support for Agent Plugins, the open, vendor-neutral spec (v1.0.0, published 2026-08-06; v1.1.0 and later 1.x manifests are also accepted; Technical Steering Committee with maintainers from Amazon, Cursor, Google, Microsoft, OpenAI, and Vercel) for bundling Agent Skills and MCP servers into one portable directory: PluginManifest/McpManifest types + structural validators on the package root, plus the bundled plugins themselves, each on a subpath named for itself (./ui-ux-design). Extracted 2026-08-18 from @jini-ai/plugins, which now only reserves the unrelated, unimplemented ./host format.",
   "license": "Apache-2.0",
   "repository": {
@@ -19,7 +19,9 @@
       "./lifecycle/node": "node",
       "./lifecycle/yauzl": "node",
       "./manifest": "universal",
-      "./persistent-state": "node"
+      "./persistent-state": "node",
+      "./folder-zip": "universal",
+      "./folder-zip/node": "node"
     },
     "isolation": {
       "entries": {
@@ -65,6 +67,16 @@
       "types": "./persistent-state.d.ts",
       "import": "./persistent-state.js",
       "default": "./persistent-state.js"
+    },
+    "./folder-zip": {
+      "types": "./dist/folder-zip.d.ts",
+      "import": "./dist/folder-zip.js",
+      "default": "./dist/folder-zip.js"
+    },
+    "./folder-zip/node": {
+      "types": "./dist/folder-zip-node.d.ts",
+      "import": "./dist/folder-zip-node.js",
+      "default": "./dist/folder-zip-node.js"
     }
   },
   "files": [

package/ui-ux-design/plugin.json

@@ -1,6 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "ui-ux-design",
+  "version": "0.4.6",
   "description": "UI/UX design, interface-design-system, accessibility, and shadcn/ui component skills bundled as one portable Agent Plugin.",
   "extensions": {
     "tovu": {