@jini-ai/agent-plugins 0.6.15-rc.2 → 0.6.16

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.6.15
+
+### Minor Changes
+
+- Add opt-in plugin source suffix exclusions and test-file inclusion. Explicit allow-paths and their ancestors now override name exclusions, while excluded descendants and suffix exclusions still skip. Default packing stays unchanged when the new options and conflicting allow/name rules are absent.
+
+  Export ResponseLimitExceededError with limitBytes from platform/fetch-with-timeout and the platform root. Guarded response-text overflow throws this RangeError subclass; invalid caps keep plain RangeError and existing truncation behavior is preserved.
+
+  Accept jsdom 26 and 27 as optional CMS peers alongside 25; media uses DOM APIs shared across these versions.
+
+- Breaking package-surface change for the fixed 0.6.15 release: remove the bundled
+  ui-ux-design files and wildcard export from @jini-ai/agent-plugins. Hosts must
+  explicitly install @jini-ai/plugin-ui-ux-design and resolve its ./plugin.json
+  export, stage that payload and seed through the existing Agent Plugin lifecycle.
+  The lifecycle implementation remains in @jini-ai/agent-plugins. Inner plugin
+  version 0.4.6, deterministic packing, digest selection and operator activation
+  decisions are preserved. Tovu wording reconciliation and cutover follow later.
+
 ## 0.6.13
 
 ### Patch Changes

package/README.md

@@ -29,7 +29,7 @@ decides its own install mechanism, permission model, and sandboxing.
 
 ## What a plugin looks like on disk
 
-A plugin is a directory. Example (this package's own bundled plugin, `ui-ux-design/`):
+A plugin is a directory. Example (`@jini-ai/plugin-ui-ux-design` publishes this payload):
 
 ```
 ui-ux-design/
@@ -104,13 +104,13 @@ Catalog format) that this package does not implement.
 | `.` (root) | universal | `PluginManifest`/`McpManifest` types, `validatePluginManifest({ value })`/`validateMcpManifest({ value })` structural validators (plus compatible `isPluginManifest(value)`/`isMcpManifest(value)` wrappers), and the known path constants (`PLUGIN_MANIFEST_FILENAME`, `PLUGIN_SKILLS_DIRNAME`, `PLUGIN_MCP_MANIFEST_FILENAME`). No filesystem access, no DOM. |
 | `./manifest` | universal | Strict manifest/MCP parsing and typed namespace readers; object structural validators are also re-exported here. |
 | `./lifecycle` | node | Host-injected installation, activation, locks, digests, bundles, trusted files, reference resolution, ranking and MCP provisioning helpers. |
+| `./lifecycle` packing | node | `createAgentPluginLifecycle(ports).packAgentPluginDirectory({ sourceDir }, { allowPaths, excludeNames, excludeSuffixes, includeTests })`; explicit allow-paths and their ancestors beat name exclusions; excluded descendants still skip. Suffix exclusions always win; test skips require `includeTests: true` to disable. |
 | `./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. |
 | `./admin-surfaces` | universal | Plugin-owned admin surfaces: the contribution definition (host-named file), sandboxed-iframe/CSP/bootstrap helpers, the host-page message gate and the server-side action dispatcher. See "Admin surfaces" below. |
 | `./admin-surfaces/client` | universal | `createAdminSurfaceClient(...)`: the self-contained surface-side protocol client a plugin's UI imports or copies. |
-| `./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
 local archive installation and host-owned activation policy; it does not implement remote catalog discovery.
@@ -150,42 +150,19 @@ package supports. Do not confuse the two — "agent plugins" (this package, a
 public spec) and "Jini plugins" (`@jini-ai/plugins`'s `./host`, Jini's own unbuilt format) share
 the word "plugin" and nothing else.
 
-## Bundled plugins
-
-Real, install-ready plugin directories shipped alongside the code — not illustrative examples.
-Each lives at the package root under **its own name** (`ui-ux-design/`).
-Plugins live at the package root rather than inside `src/` because `src/` is the TypeScript
-compile root (`rootDir: "src"`, `include: ["src"]`) — a plugin's skill trees can carry files
-(`.tsx` examples, etc.) that are illustrative content, not package code, and putting them under
-`src/` makes `tsc` try to compile them (measured, on `ui-ux-design`: 207 errors from the three
-`shadcn-ui/examples/*.tsx` files alone). Static content and compiler input are kept in separate
-trees on purpose.
-
-### `ui-ux-design/`
-
-Bundles the AI-Dev-Shop Web Design agent's full skill set (per its `agents/web-design/skills.md`
-persona and the `framework/routing/skills-registry.md` ownership mapping) into one portable plugin:
-
-- `ui-ux-design` — design-foundations (tokens, typography, spacing, breakpoints, component state
-  matrix) *and* first-impression polish, scanning hierarchy, conversion-focused visual signals —
-  one skill, not two. AI-Dev-Shop merged its former separate `ux-design` and `premium-ui` skills
-  into this single `ui-ux-design` skill; this sample tracks that merge instead of carrying the two
-  predecessor skills as stale copies (see git history for the 2026-08-12 consolidation).
-- `interface-design` — repeatable, memory-consistent visual systems for dashboards/admin panels/apps
-- `gstack-design` — manual four-mode workflow (consultation, shotgun, html, review)
-- `frontend-accessibility` — WCAG 2.1 AA checklist
-- `vercel-web-design-guidelines` — Vercel Web Interface Guidelines auditor
-- `shadcn-ui` — shadcn/ui (Radix + Tailwind) component discovery/integration guidance
-- `web-compliance` — legal/compliance checkpoints for public-facing UX flows
-
-Each skill directory is a verbatim copy of the corresponding `AI-Dev-Shop/skills/<name>/` tree —
-copied rather than referenced, because the whole point of a plugin is that it is self-contained and
-portable to a host that has never heard of AI-Dev-Shop. `AI-Dev-Shop/agents/web-design/skills.md`
-itself (the persona that composes these skills into one role) is not bundled — it is ADS-specific
-routing glue, not a portable skill.
-
-Consumers may read bundled raw assets through the public wildcard subpath. Product-specific
-plugin assets are owned and shipped by their product, outside this library.
+## Independently packaged plugins
+
+Starting with the breaking 0.6.16 release, this library ships manifest and lifecycle code only.
+Install `@jini-ai/plugin-ui-ux-design` explicitly for the design payload. Resolve
+`@jini-ai/plugin-ui-ux-design/plugin.json`; its containing directory holds the portable assets.
+Stage that directory beneath the host's bundled-source root, then call the existing
+`seedBundledAgentPlugins({ layout, workspaceId, sourceRoot })`. Read contributions through trusted
+installed-package readers. Seeding preserves digest selection and operator activation decisions.
+
+The editable design source remains at `ui-ux-design/` here, outside `src/`: its `.tsx` examples
+are illustrative skill content and must not enter the TypeScript compile root. Assembly generates
+only the standalone package's payload. The old `@jini-ai/agent-plugins/ui-ux-design/*` export is
+removed; product-specific assets remain owned by their product.
 
 ## Scripts
 
@@ -198,18 +175,12 @@ pnpm --filter @jini-ai/agent-plugins test
 The build and typecheck include lifecycle test sources. Copied Node test options are
 translated to Vitest registration, preserving per-test timeouts and platform skip conditions.
 
-## Adding another bundled plugin
-
-1. Create `<plugin-name>/plugin.json` at the package root with at least
-   `{ "$schema": AGENT_PLUGINS_SCHEMA_URL, "name": "<plugin-name>" }`. Do **not** put it under
-   `src/` — see "Bundled plugins" above for why.
-2. Add `<plugin-name>/skills/<skill-name>/SKILL.md` per skill (plus any `references/`,
-   `examples/`, `scripts/` the skill needs).
-3. Register it in `package.json`: an `exports` key `"./<plugin-name>/*": "./<plugin-name>/*"`, a
-   matching `jini.entries` key (the R8 guard requires every export to have one), and a
-   `files` entry.
-4. Add coverage in `src/__tests__/manifest.test.ts` following the `ui-ux-design plugin` block — assert the manifest validates and the expected skill
-   directories exist.
+## Adding another plugin
+
+Create a separate `@jini-ai/plugin-<id>` workspace package with its own reviewed manifest,
+README, LICENSE and NOTICE. Generate only that plugin's payload; do not add plugin assets or
+plugin dependencies to this lifecycle library. Keep skill trees outside TypeScript compile roots,
+validate the plugin manifest and test installation through this package's existing lifecycle.
 
 ## Lifecycle API and ports
 

package/dist/admin-surfaces/action-tools.js

@@ -40,7 +40,7 @@ export function buildAdminSurfaceActionTools(required, optional = {}) {
                     await required.authorize({ context });
                     const payload = checkedPayload({ input, action });
                     const dispatcher = createAdminSurfaceActionDispatcher({ descriptor, handlers: required.handlersFor({ pluginId, surfaceId: descriptor.id }) });
-                    const dispatch = () => dispatcher.dispatch({ action: action.name, payload, context });
+                    const dispatch = dispatcher.dispatch.bind(dispatcher, { action: action.name, payload, context });
                     return optional.run ? optional.run({ dispatch }) : dispatch();
                 },
             },

package/dist/admin-surfaces/external-links.js

@@ -20,7 +20,8 @@ function isOpenLinkEnvelope(data) {
         return false;
     const message = data;
     const isProtocol = message.protocol === ADMIN_SURFACE_PROTOCOL && message.version === ADMIN_SURFACE_PROTOCOL_VERSION && message.kind === 'open-link';
-    return isProtocol && typeof message.mountId === 'string' && typeof message.requestId === 'string' && REQUEST_ID_PATTERN.test(message.requestId) && typeof message.url === 'string';
+    const hasRequestId = typeof message.requestId === 'string' && REQUEST_ID_PATTERN.test(message.requestId);
+    return isProtocol && typeof message.mountId === 'string' && hasRequestId && typeof message.url === 'string';
 }
 /** The normalized URL when `raw` may be opened, or why not. Messages never echo the URL. @complexity O(n) in the URL length. */
 function checkLink(raw, origins) {

package/dist/admin-surfaces/host-validator.js

@@ -18,8 +18,8 @@ function isRequestEnvelope(data) {
     return isProtocol && hasRequestFields(message);
 }
 function hasRequestFields(message) {
-    return typeof message.mountId === 'string' && typeof message.requestId === 'string' && REQUEST_ID_PATTERN.test(message.requestId)
-        && typeof message.action === 'string' && Object.hasOwn(message, 'payload');
+    const hasRequestId = typeof message.requestId === 'string' && REQUEST_ID_PATTERN.test(message.requestId);
+    return typeof message.mountId === 'string' && hasRequestId && typeof message.action === 'string' && Object.hasOwn(message, 'payload');
 }
 /** Character length of the payload as JSON, or Infinity when it is not JSON-serializable. */
 /** Whether `event` comes from `mount`'s frame at all (origin and window), for every inbound message kind.

package/dist/admin-surfaces/settings-value.js

@@ -10,7 +10,9 @@ import { PLUGIN_STATE_MAX_KEY_LENGTH } from '../lifecycle/tools/capabilities.js'
 export const ADMIN_SURFACE_STATE_LIMITS = Object.freeze({ maxKeyLength: PLUGIN_STATE_MAX_KEY_LENGTH, maxValueBytes: 16 * 1024, maxDepth: 16 });
 export const STATE_CREDENTIAL_MESSAGE = 'The plugin tried to save a connection credential in its settings; nothing was saved.';
 function isStateScalar(value) {
-    return value === null || typeof value === 'string' || typeof value === 'boolean' || (typeof value === 'number' && Number.isFinite(value));
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    return value === null || typeof value === 'string' || typeof value === 'boolean';
 }
 /** True for plain JSON data only: no undefined, functions, NaN, class instances or deep nesting. @complexity O(n) nodes. */
 function isStateValue(value, depth) {

package/dist/admin-surfaces/surface-client.js

@@ -43,6 +43,12 @@ function isFailure(value) {
     const error = value;
     return typeof error.code === 'string' && typeof error.message === 'string' && typeof error.retryable === 'boolean';
 }
+/** A non-empty, bounded token value with nothing that could escape a CSS custom property. */
+function isSafeThemeValue(token) {
+    if (typeof token !== 'string')
+        return false;
+    return token.length > 0 && token.length <= 200 && !UNSAFE_THEME_VALUE.test(token);
+}
 /** The host's theme with every unknown name or unsafe value dropped; undefined when it is not a theme. */
 function acceptedTheme(value) {
     if (typeof value !== 'object' || value === null)
@@ -50,8 +56,7 @@ function acceptedTheme(value) {
     const { scheme, tokens } = value;
     if ((scheme !== 'light' && scheme !== 'dark') || typeof tokens !== 'object' || tokens === null)
         return undefined;
-    const safe = Object.entries(tokens).slice(0, MAX_THEME_TOKENS).filter(([name, token]) => THEME_TOKEN.test(name)
-        && typeof token === 'string' && token.length > 0 && token.length <= 200 && !UNSAFE_THEME_VALUE.test(token));
+    const safe = Object.entries(tokens).slice(0, MAX_THEME_TOKENS).filter(([name, token]) => THEME_TOKEN.test(name) && isSafeThemeValue(token));
     return { scheme, tokens: Object.fromEntries(safe) };
 }
 /** The browser root when there is a document (none in a server-side test). */
@@ -158,13 +163,16 @@ export function createAdminSurfaceClient(required, optional = {}) {
     const unsubscribe = required.listen((event) => {
         if (event.source !== required.parent)
             return;
-        if (isMessage(event.data, 'init'))
+        if (isMessage(event.data, 'init')) {
             onInit(event, event.data);
-        else if (isMessage(event.data, 'theme')) {
+            return;
+        }
+        if (isMessage(event.data, 'theme')) {
             if (event.origin === init?.origin && event.data.mountId === init.mountId)
                 applyTheme(event.data.theme);
+            return;
         }
-        else if (isMessage(event.data, 'action-response'))
+        if (isMessage(event.data, 'action-response'))
             onResponse(event, event.data);
     });
     /** Posts one request of `kind` to the host origin and waits for its `action-response`. */

package/dist/core/plugin-name.d.ts

@@ -0,0 +1,11 @@
+export declare const MAX_NAME_LENGTH = 64;
+/**
+ * True when `value` is a valid Agent Plugin id: `plugin.json`'s `name` grammar (§5.5, see
+ * `NAME_PATTERN`), 1-64 characters. The one owner of that grammar: a host checks an id taken from a
+ * URL or a tool input here before it names anything on disk, instead of restating the pattern.
+ * @complexity O(n) in the value's length.
+ */
+export declare function isAgentPluginName({ value }: {
+    readonly value: unknown;
+}, _optional?: Record<string, never>): boolean;
+//# sourceMappingURL=plugin-name.d.ts.map

package/dist/core/plugin-name.js

@@ -0,0 +1,19 @@
+/**
+ * §5.5's grammar as one regex: alnum runs separated by single `-`/`.` delimiters. This shape alone
+ * guarantees start/end are alphanumeric (the regex can only start and end on `[a-z0-9]+`) AND that
+ * no two delimiters are ever adjacent (a delimiter is always followed by at least one alnum char
+ * before the next one can appear) — so "no leading/trailing hyphen" and "no consecutive delimiters"
+ * fall out of one pattern rather than needing separate checks that could disagree.
+ */
+const NAME_PATTERN = /^[a-z0-9]+(?:[-.][a-z0-9]+)*$/;
+export const MAX_NAME_LENGTH = 64;
+/**
+ * True when `value` is a valid Agent Plugin id: `plugin.json`'s `name` grammar (§5.5, see
+ * `NAME_PATTERN`), 1-64 characters. The one owner of that grammar: a host checks an id taken from a
+ * URL or a tool input here before it names anything on disk, instead of restating the pattern.
+ * @complexity O(n) in the value's length.
+ */
+export function isAgentPluginName({ value }, _optional = {}) {
+    return typeof value === "string" && value.length <= MAX_NAME_LENGTH && NAME_PATTERN.test(value);
+}
+//# sourceMappingURL=plugin-name.js.map

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

@@ -8,4 +8,25 @@ export declare function zipLocalFolder(required: {
     path: string;
     maxBytes: number;
 }, _optional?: Record<string, never>): Promise<Uint8Array>;
+export interface CustomizeAgentPluginFolderInput {
+    readonly path: string;
+    readonly maxBytes: number;
+    readonly name: string;
+    readonly identityNamespace: string;
+    readonly edit: {
+        readonly path: string;
+        readonly oldString: string;
+        readonly newString: string;
+    };
+}
+/**
+ * Fork a captured Agent Plugin package with one exact text edit and a fresh identity.
+ * Uses the folder upload reader/encoder; never writes into an immutable installed package.
+ * @param required Source folder, byte ceiling, new local id, host namespace and literal edit.
+ * @returns ZIP bytes for the existing upload preview/installer. Does not grant bundled trust.
+ * @throws {FolderZipError} Unsafe/missing paths, links, non-unique text, identity or size refusal.
+ * @complexity O(e log e + b) time and O(e + b) space, bounded by upload entry/byte ceilings.
+ * @example zipCustomizedAgentPluginFolder({ path, maxBytes, name: 'my-plugin', identityNamespace: 'host', edit })
+ */
+export declare function zipCustomizedAgentPluginFolder(required: CustomizeAgentPluginFolderInput, _optional?: Record<string, never>): Promise<Uint8Array>;
 //# sourceMappingURL=folder-zip-node.d.ts.map

package/dist/folder-zip-node.js

@@ -2,6 +2,13 @@ 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";
+import { isAgentPluginName } from './core/plugin-name.js';
+/** Code-unit order, independent of locale. */
+function compareCodeUnits(a, b) {
+    if (a === b)
+        return 0;
+    return a < b ? -1 : 1;
+}
 async function readLocalFile(required, _optional = {}) {
     const { filesystem, root, filename, name, maxBytes } = required;
     if (await filesystem.realpath(filename) !== filename)
@@ -41,7 +48,8 @@ async function collectDirectory(required, _optional = {}) {
     const handle = await filesystem.opendir(directory);
     // Mutate the traversal's owned buffers so visiting directories does not copy accumulated files.
     for await (const entry of handle) {
-        if (++collection.entries > FOLDER_MAX_FILES)
+        collection.entries += 1;
+        if (collection.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()) {
@@ -62,6 +70,10 @@ async function collectDirectory(required, _optional = {}) {
  * bounded to 4096 entries and maxBytes. No network I/O.
  */
 export async function zipLocalFolder(required, _optional = {}) {
+    return encodeLocalFiles({ files: await collectLocalFiles(required), maxBytes: required.maxBytes });
+}
+/** Shared bounded, no-link directory reader for uploads and customized copies. No writes. */
+async function collectLocalFiles(required) {
     const collection = { files: [], pending: [], entries: 0, total: 0 };
     try {
         const root = await fs.realpath(required.path);
@@ -72,8 +84,8 @@ export async function zipLocalFolder(required, _optional = {}) {
         }
         const { files } = collection;
         // 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());
+        files.sort((a, b) => compareCodeUnits(a.webkitRelativePath, b.webkitRelativePath));
+        return files;
     }
     catch (error) {
         if (error instanceof FolderZipError)
@@ -81,4 +93,74 @@ export async function zipLocalFolder(required, _optional = {}) {
         throw new FolderZipError("unreadable", FOLDER_UNREADABLE);
     }
 }
+/** Encode through the upload owner, rechecking the byte budget after any transformation. */
+async function encodeLocalFiles({ files, maxBytes }) {
+    return new Uint8Array(await (await zipFolderFiles({ files, maxBytes })).arrayBuffer());
+}
+/** Replace captured bytes while preserving the upload encoder's relative path. */
+function replaceCapturedFile({ file, text }) {
+    const next = new File([text], file.name);
+    Object.defineProperty(next, 'webkitRelativePath', { value: file.webkitRelativePath });
+    return next;
+}
+/** Non-UTF-8 or NUL-bearing bytes are binary; refuse them as a named error, not a decoder TypeError. */
+function decodeEditableText(bytes) {
+    let text;
+    try {
+        text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    }
+    catch {
+        text = '\0';
+    }
+    if (text.includes('\0'))
+        throw new FolderZipError('unreadable', 'Binary files cannot be edited as text.');
+    return text;
+}
+/** Require exactly one literal match; `$&` and other replacement syntax remain plain text. */
+function customizeText({ text, edit }) {
+    if (!edit.oldString)
+        throw new FolderZipError('unreadable', 'oldString must not be empty.');
+    const index = text.indexOf(edit.oldString);
+    if (index < 0 || text.indexOf(edit.oldString, index + edit.oldString.length) >= 0) {
+        throw new FolderZipError('unreadable', 'oldString must match exactly once. Read the file and send more context.');
+    }
+    return text.slice(0, index) + edit.newString + text.slice(index + edit.oldString.length);
+}
+/** A fork must not retain its publisher identity or historical aliases and supersession claims. */
+function customizeManifest({ text, name, identityNamespace }) {
+    const manifest = JSON.parse(text);
+    if (!isAgentPluginName({ value: name }) || manifest.name === name) {
+        throw new FolderZipError('unreadable', 'Choose a valid new Agent Plugin id different from the source.');
+    }
+    manifest.name = name;
+    const extension = manifest.extensions?.[identityNamespace];
+    if (extension) {
+        extension.id = `local/${name}`;
+        delete extension.renamedFrom;
+        delete extension.supersedes;
+    }
+    return JSON.stringify(manifest, null, 2) + '\n';
+}
+/**
+ * Fork a captured Agent Plugin package with one exact text edit and a fresh identity.
+ * Uses the folder upload reader/encoder; never writes into an immutable installed package.
+ * @param required Source folder, byte ceiling, new local id, host namespace and literal edit.
+ * @returns ZIP bytes for the existing upload preview/installer. Does not grant bundled trust.
+ * @throws {FolderZipError} Unsafe/missing paths, links, non-unique text, identity or size refusal.
+ * @complexity O(e log e + b) time and O(e + b) space, bounded by upload entry/byte ceilings.
+ * @example zipCustomizedAgentPluginFolder({ path, maxBytes, name: 'my-plugin', identityNamespace: 'host', edit })
+ */
+export async function zipCustomizedAgentPluginFolder(required, _optional = {}) {
+    const files = await collectLocalFiles(required);
+    // Match captured package paths, never join a model-supplied edit path onto the filesystem.
+    const target = files.findIndex(file => file.webkitRelativePath === `folder/${required.edit.path}`);
+    const manifest = files.findIndex(file => file.webkitRelativePath === 'folder/plugin.json');
+    if (target < 0 || manifest < 0 || target === manifest) {
+        throw new FolderZipError('unreadable', 'Choose an existing package-relative text file other than plugin.json.');
+    }
+    const text = decodeEditableText(new Uint8Array(await files[target].arrayBuffer()));
+    files[target] = replaceCapturedFile({ file: files[target], text: customizeText({ text, edit: required.edit }) });
+    files[manifest] = replaceCapturedFile({ file: files[manifest], text: customizeManifest({ text: await files[manifest].text(), name: required.name, identityNamespace: required.identityNamespace }) });
+    return encodeLocalFiles({ files, maxBytes: required.maxBytes });
+}
 //# sourceMappingURL=folder-zip-node.js.map

package/dist/lifecycle/activation.js

@@ -87,10 +87,10 @@ export class AgentPluginActivationsBusyError extends Error {
     holder;
     lost;
     constructor({ lockPath, holder, lost }) {
+        const holderNote = holder !== undefined ? ` — held by pid ${holder.pid} on ${holder.hostname} since ${holder.acquiredAt}` : " — holder unknown";
         super((lost
             ? `agent-plugin activation: lost the write lock (${lockPath}) before committing — another process judged it stale`
-            : `agent-plugin activation: could not take the write lock (${lockPath}) within 15s` +
-                (holder !== undefined ? ` — held by pid ${holder.pid} on ${holder.hostname} since ${holder.acquiredAt}` : " — holder unknown")) +
+            : `agent-plugin activation: could not take the write lock (${lockPath}) within 15s` + holderNote) +
             ". Nothing was written, so no recorded enable/disable decision was changed. This clears by itself when the other " +
             "host process (server, agent daemon, or the agent-plugin:activation CLI) finishes; a lock left by a crashed " +
             "process is removed automatically once that process is gone or the lock is older than 10s. If it persists, stop " +

package/dist/lifecycle/automatic-use.js

@@ -116,20 +116,25 @@ export function createAutomaticAgentPluginUse({ mode, state: initialState, ports
      */
     async function resolveGuidance({ matches }, { signal } = {}) {
         const guidance = [];
-        for (const match of matches) {
-            if (signal?.aborted)
-                break;
+        // Unloaded plugins contribute nothing; oversized guidance becomes a pointer instead of the text.
+        const guidanceFor = async (match) => {
             const result = await resolveOneGuidance({ plugin: match }, { signal });
             if (result.status !== 'loaded')
-                continue;
+                return undefined;
             if (new TextEncoder().encode(result.guidance).length > MAX_AUTOMATIC_GUIDANCE_BYTES) {
                 const pointer = ports.formatPluginToolPointer?.({ pluginId: match.pluginId, skill: match.pluginId, file: 'SKILL.md' });
                 const howToLoad = pointer === undefined ? '' : ` Load the full instructions with ${pointer}; use the same call with file '<relative path>' for supporting references.`;
-                guidance.push(`Agent Plugin '${match.pluginId}' guidance is deferred because it exceeds the automatic byte limit.${howToLoad}`);
-                continue;
+                return `Agent Plugin '${match.pluginId}' guidance is deferred because it exceeds the automatic byte limit.${howToLoad}`;
             }
             recordDelivery({ plugin: match, result });
-            guidance.push(result.guidance);
+            return result.guidance;
+        };
+        for (const match of matches) {
+            if (signal?.aborted)
+                break;
+            const text = await guidanceFor(match);
+            if (text !== undefined)
+                guidance.push(text);
         }
         return guidance;
     }

package/dist/lifecycle/bundled-digests.js

@@ -115,14 +115,9 @@ function buildModule(ports) {
             return EMPTY_LEDGER;
         const digests = new Map();
         for (const [pluginId, entry] of Object.entries(value.plugins)) {
-            if (!SAFE_PLUGIN_ID_PATTERN.test(pluginId))
-                continue;
-            if (!isPlainObject(entry))
-                continue;
-            const { archiveDigest } = entry;
-            if (typeof archiveDigest !== "string" || !SHA256_DIGEST_PATTERN.test(archiveDigest))
-                continue;
-            digests.set(pluginId, archiveDigest);
+            const archiveDigest = SAFE_PLUGIN_ID_PATTERN.test(pluginId) && isPlainObject(entry) ? entry.archiveDigest : undefined;
+            if (typeof archiveDigest === "string" && SHA256_DIGEST_PATTERN.test(archiveDigest))
+                digests.set(pluginId, archiveDigest);
         }
         return digests;
     }

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

@@ -13,10 +13,16 @@ export interface PackedAgentPluginArchive {
 }
 /** Opt-in source selection, resource bounds and archive identity. Omission preserves bundled-v1. */
 export interface PackAgentPluginDirectoryOptional {
-    /** Exact package-relative files or directory subtrees. Empty selects nothing; exclusions win. */
+    /** Exact package-relative files or directory subtrees. Empty selects nothing. An explicit path
+     * and its ancestors override excludeNames; excluded descendants of a selected subtree still skip.
+     * Suffix exclusions and default test skips win even over explicit paths. */
     readonly allowPaths?: readonly string[];
-    /** Entry basenames excluded at every depth, before entering directories. */
+    /** Entry basenames excluded at every depth unless explicitly allowed (or needed to reach one). */
     readonly excludeNames?: readonly string[];
+    /** Case-sensitive path suffixes excluded at every depth, including directories and explicit paths. */
+    readonly excludeSuffixes?: readonly string[];
+    /** Include __tests__ directories and .test./.spec. files. Defaults to false; other filters still apply. */
+    readonly includeTests?: boolean;
     /** Nonnegative safe integers; root depth is zero. Supplied bounds fail rather than truncate. */
     readonly limits?: {
         readonly maxEntries: number;

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

@@ -262,10 +262,11 @@ function buildModule(ports) {
     }
     /**
    * Lists runtime regular files under `dir`, as POSIX-style package-relative paths.
-   * Test directories and test/spec files are excluded so test-only edits cannot change installed
+   * By default, test directories and test/spec files are excluded so test-only edits cannot change installed
    * runtime contents or their content-addressed digest.
    *
-   * @complexity O(e * a) selection checks for e enumerated entries and a allowlist paths (one when omitted).
+   * @complexity O(e * (a + s)) selection checks for e entries, a allowlist paths and s suffixes.
+   * Path comparison cost scales with path length; selection uses O(1) auxiliary space per entry.
    */
     async function listRegularFiles({ dir, prefix, depth, state }) {
         const entries = await readdir(dir, { withFileTypes: true });
@@ -274,9 +275,8 @@ function buildModule(ports) {
         const files = [];
         for (const entry of entries) {
             const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
-            if (state.excluded.has(entry.name))
-                continue;
-            if (!selectPath({ relative, directory: entry.isDirectory(), state }))
+            const directory = entry.isDirectory();
+            if (isNameExcluded({ name: entry.name, relative, directory, state }) || !selectPath({ relative, directory, state }))
                 continue;
             if (entry.isDirectory()) {
                 files.push(...await directoryEntryFiles({ name: entry.name, dir, relative, depth, state }));
@@ -289,13 +289,13 @@ function buildModule(ports) {
         return files;
     }
     async function directoryEntryFiles({ name, dir, relative, depth, state }) {
-        if (name === '__tests__')
+        if (name === '__tests__' && !state.options.includeTests)
             return [];
         assertPackingLimit({ state, name: 'maxDepth', value: depth + 1 });
         return listRegularFiles({ dir: path.join(dir, name), prefix: relative, depth: depth + 1, state });
     }
     function regularEntryFiles({ entry, relative, state }) {
-        if (entry.isFile() && !/\.(test|spec)\./.test(entry.name)) {
+        if (entry.isFile() && (state.options.includeTests || !/\.(test|spec)\./.test(entry.name))) {
             recordFile({ relative, state });
             return [relative];
         }
@@ -307,8 +307,17 @@ function buildModule(ports) {
         state.files.add(relative);
         assertPackingLimit({ state, name: 'maxFiles', value: state.files.size });
     }
-    /** Ancestors of an allowed path must be traversed, but their unrelated siblings are pruned. */
+    /** An exact allow-path reopens excluded ancestors without reopening unrelated siblings.
+     * A selected subtree does not implicitly override name exclusions farther down that subtree.
+     * @complexity O(a * p) time for a allow-paths of length p, O(1) space. No I/O or mutation. */
+    function isNameExcluded({ name, relative, directory, state }) {
+        return state.excluded.has(name) && !state.allowPaths?.some(allowed => relative === allowed || (directory && allowed.startsWith(`${relative}/`)));
+    }
+    /** Ancestors of an allowed path must be traversed, but their unrelated siblings are pruned.
+     * Suffix exclusions always win. O((a + s) * p) time, O(1) space; no I/O or mutation. */
     function selectPath({ relative, directory, state }) {
+        if (state.options.excludeSuffixes?.some(suffix => relative.endsWith(suffix)))
+            return false;
         return state.allowPaths === undefined || state.allowPaths.some(allowed => relative === allowed || relative.startsWith(`${allowed}/`) || (directory && allowed.startsWith(`${relative}/`)));
     }
     function refuseEntry({ state, entryPath, symlink }) {

package/dist/lifecycle/contribution-loader.js

@@ -49,12 +49,11 @@ export function createPluginContributionLoader(required, _optional = {}) {
                 refusals.push(verdict.refusal);
                 continue;
             }
+            // A host package policy refusal stands in for the plugin's contributions.
             const refusal = packageRefusal?.({ plugin: verdict.trusted });
-            if (refusal !== undefined) {
-                refusals.push(refusal);
-                continue;
-            }
-            const loaded = await loadPluginContributionsFromSource({ plugin: verdict.trusted, definition });
+            const loaded = refusal === undefined
+                ? await loadPluginContributionsFromSource({ plugin: verdict.trusted, definition })
+                : { items: [], refusals: [refusal] };
             items.push(...loaded.items);
             refusals.push(...loaded.refusals);
         }

package/dist/lifecycle/index.d.ts

@@ -7,7 +7,6 @@ import { maxAgentPluginArchiveBytes } from './fetch-archive.js';
 import type { FetchAgentPluginArchiveOptional } from './fetch-archive.js';
 import type { PackAgentPluginDirectoryOptional } from './bundled-source-archive.js';
 import type { AgentPluginLifecycleRequired, AgentPluginLifecycleOptional } from './ports.js';
-import type { AgentPluginDeliveryMode } from './resolve-agent-plugin-refs.js';
 import type { InstalledDigestIdentity } from './bundled-digests.js';
 export type { SeededAgentPluginOutcome, SeedBundledAgentPluginsRequired, SeedBundledAgentPluginsOptional, SeedBundledAgentPluginsResult, PackingForSource } from './seed-bundled.js';
 export type { RetireBundledAgentPluginsRequired, RetireBundledAgentPluginsOptional, RetiredAgentPluginOutcome, RetiredAgentPluginSuccessorOutcome } from './retire-bundled.js';
@@ -167,7 +166,7 @@ export declare function createAgentPluginLifecycle(required: AgentPluginLifecycl
         pluginRefIds: readonly string[];
         workspaceLayout: Pick<import("./layout.js").AgentPluginWorkspaceLayout, "packages" | "root">;
     }, { deliveryMode, ...request }?: import("./resolve-agent-plugin-refs.js").AgentPluginSkillRequest & {
-        deliveryMode?: AgentPluginDeliveryMode;
+        deliveryMode?: import("./types.js").AgentPluginDeliveryMode;
     }) => Promise<import("./resolve-agent-plugin-refs.js").ResolveAgentPluginRefsResult>;
     pluginMemory: (input: {
         readonly workspaceId: string;