@jini-ai/agent-plugins 0.4.6 → 0.4.8

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

@@ -0,0 +1,128 @@
+/** 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 and validates `packageRoot`'s `plugin.json`, refusing a missing, unparseable or invalid one. */
+    async function readInstalledManifest({ packageRoot }) {
+        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("; ")}` });
+        }
+        return parsed;
+    }
+    /** Every regular file under `packageRoot` (sorted) and every `skills/<name>/SKILL.md` (sorted by name). */
+    async function walkPackageTree({ packageRoot }) {
+        const files = [];
+        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);
+                // 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, "");
+        for (const relative of files) {
+            const match = relative.match(/^skills\/([^/]+)\/SKILL\.md$/);
+            if (match)
+                skills.push({ name: match[1], skillPath: relative });
+        }
+        return { files: files.sort(), skills: skills.sort((a, b) => a.name.localeCompare(b.name)) };
+    }
+    /**
+   * 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 = {}) {
+        const parsed = await readInstalledManifest({ packageRoot });
+        for (const message of parsed.warnings)
+            ports.onEvent?.({ event: 'agent-plugin-identity-warning', message });
+        const { files, skills } = await walkPackageTree({ packageRoot });
+        return {
+            pluginId: parsed.manifest.name,
+            id: parsed.manifest.id,
+            provides: parsed.manifest.provides,
+            ...(parsed.manifest.requires === undefined ? {} : { requires: parsed.manifest.requires }),
+            ...(parsed.manifest.hostRange === undefined ? {} : { hostRange: parsed.manifest.hostRange }),
+            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,
+            skills,
+        };
+    }
+    return { indexInstalledRoot };
+}
+//# sourceMappingURL=installed-package-index.js.map

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

@@ -9,12 +9,14 @@ export const INSTALLED_PLUGIN_DIGEST_PATTERN = /^[a-f0-9]{64}$/;
  * @complexity O(d) directory/containment operations for d revisions; no executable imports.
  */
 export async function listInstalledPackageRoots({ ports, workspaceRoot }, _optional = {}) {
-    const persistentState = createPersistentStateModule(ports);
-    const { assertContainedOnDisk } = createPackagePathsModule(ports);
-    const readdir = ports.filesystem.readdir.bind(ports.filesystem);
+    const effects = {
+        readdir: ports.filesystem.readdir.bind(ports.filesystem),
+        assertOwnedPath: createPersistentStateModule(ports).assertOwnedPath,
+        assertContainedOnDisk: createPackagePathsModule(ports).assertContainedOnDisk,
+    };
     let folders;
     try {
-        folders = await readdir(workspaceRoot, { withFileTypes: true });
+        folders = await effects.readdir(workspaceRoot, { withFileTypes: true });
     }
     catch (error) {
         if (isEnoent(error))
@@ -25,25 +27,31 @@ export async function listInstalledPackageRoots({ ports, workspaceRoot }, _optio
     for (const folder of folders) {
         if (!folder.isDirectory() || !/^[a-z0-9]+(?:[-.][a-z0-9]+)*$/.test(folder.name) || folder.name.length > 64)
             continue;
-        const packagesDir = path.join(workspaceRoot, folder.name, 'package', 'sha256');
-        let entries;
+        roots.push(...await listFolderRevisions({ effects, workspaceRoot, localId: folder.name }));
+    }
+    return roots;
+}
+/** One plugin folder's contained digest revisions; a folder with no owned package store has none. */
+async function listFolderRevisions({ effects, workspaceRoot, localId }) {
+    const packagesDir = path.join(workspaceRoot, localId, 'package', 'sha256');
+    let entries;
+    try {
+        await effects.assertOwnedPath({ workspaceRoot, entryPath: path.relative(workspaceRoot, packagesDir) });
+        entries = await effects.readdir(packagesDir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const roots = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory() || !INSTALLED_PLUGIN_DIGEST_PATTERN.test(entry.name))
+            continue;
         try {
-            await persistentState.assertOwnedPath({ workspaceRoot, entryPath: path.relative(workspaceRoot, packagesDir) });
-            entries = await readdir(packagesDir, { withFileTypes: true });
+            const packageRoot = await effects.assertContainedOnDisk(workspaceRoot, path.relative(workspaceRoot, path.join(packagesDir, entry.name)));
+            roots.push({ localId, archiveDigest: entry.name, packageRoot });
         }
         catch {
-            continue;
-        }
-        for (const entry of entries) {
-            if (!entry.isDirectory() || !INSTALLED_PLUGIN_DIGEST_PATTERN.test(entry.name))
-                continue;
-            try {
-                const packageRoot = await assertContainedOnDisk(workspaceRoot, path.relative(workspaceRoot, path.join(packagesDir, entry.name)));
-                roots.push({ localId: folder.name, archiveDigest: entry.name, packageRoot });
-            }
-            catch {
-                // One corrupt package never hides another plugin. Memory-only folders are not installs.
-            }
+            // One corrupt package never hides another plugin. Memory-only folders are not installs.
         }
     }
     return roots;

package/dist/lifecycle/manifest.d.ts

@@ -8,6 +8,15 @@ export type AgentPluginServerMetadataReader = (required: {
     readonly value: Readonly<Record<string, unknown>>;
     readonly server: Readonly<Record<string, unknown>>;
 }) => Readonly<Record<string, unknown>>;
+/**
+ * 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;
 export interface AgentPluginManifest {
     readonly name: string;
     readonly version?: (string) | undefined;
@@ -19,6 +28,10 @@ export interface AgentPluginManifest {
     /** Normalized publisher identity, independent of name/storage key and version. */
     readonly id?: string | undefined;
     readonly provides?: readonly string[] | undefined;
+    /** `extensions.<ns>.requires`: advisory capability ids other active plugins should provide. */
+    readonly requires?: readonly string[] | undefined;
+    /** `extensions.<ns>.hostRange`: semver range over AGENT_PLUGIN_CONTRACT_VERSION; a malformed value is stored as `<invalid>`. */
+    readonly hostRange?: string | undefined;
 }
 export type ParseAgentPluginManifestResult = {
     readonly ok: true;
@@ -30,6 +43,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

@@ -54,6 +54,7 @@
  * own "receives a JS value, never a file path or raw bytes" contract. `install.ts` is the only
  * caller that reads the file and hands the parsed value here.
  */
+import { readAgentPluginCompatibilityMetadata } from "./compatibility-metadata.js";
 import { readPluginIdentity, validatePluginIdentity } from "@jini-ai/core/plugin-directory";
 export { validatePluginManifest, validateMcpManifest } from '../manifest.js';
 /**
@@ -104,6 +105,15 @@ function readSpecVersion(value, file) {
  */
 const NAME_PATTERN = /^[a-z0-9]+(?:[-.][a-z0-9]+)*$/;
 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);
+}
 const KNOWN_MANIFEST_KEYS = new Set(["$schema", "name", "version", "description", "author", "license", "keywords", "extensions"]);
 /**
  * True for a non-null, non-array plain object — the "is this actually a JSON object" gate both
@@ -112,6 +122,17 @@ const KNOWN_MANIFEST_KEYS = new Set(["$schema", "name", "version", "description"
 function isJsonObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+/**
+ * `undefined` for an absent optional field, otherwise whatever `parse` makes of it — `null` meaning
+ * present but malformed, which every caller folds into rejecting the whole entry.
+ */
+function parseOptional({ value, parse }) {
+    return value === undefined ? undefined : parse(value);
+}
+/** Drops `undefined` members, so an absent optional field stays absent rather than present-as-undefined. */
+function definedFields(fields) {
+    return Object.fromEntries(Object.entries(fields).filter(([, value]) => value !== undefined));
+}
 /**
  * `value` narrowed to a `string`, or `undefined` — every optional string field below coerces
  * through this one check instead of repeating its own `typeof ... === "string" ? ... : undefined`
@@ -125,11 +146,7 @@ function parseManifestAuthor(value) {
         return value; // Existing installed manifests may carry a string.
     if (!isJsonObject(value))
         return undefined;
-    return {
-        ...(typeof value.name === 'string' ? { name: value.name } : {}),
-        ...(typeof value.email === 'string' ? { email: value.email } : {}),
-        ...(typeof value.url === 'string' ? { url: value.url } : {}),
-    };
+    return definedFields({ name: coerceOptionalString(value.name), email: coerceOptionalString(value.email), url: coerceOptionalString(value.url) });
 }
 /**
  * Validates `plugin.json`'s `name` field per §5.5's grammar (see `NAME_PATTERN`'s own header for
@@ -141,25 +158,15 @@ function resolveManifestName(raw) {
     const name = coerceOptionalString(raw.name);
     if (name === undefined)
         return { error: "plugin.json 'name' is required and must be a string" };
-    if (name.length === 0 || name.length > MAX_NAME_LENGTH || !NAME_PATTERN.test(name)) {
+    if (!isAgentPluginName({ value: name })) {
         return {
             error: `plugin.json 'name' ('${name}') must be 1-${MAX_NAME_LENGTH} lowercase alphanumeric/hyphen/period characters, start and end alphanumeric, with no consecutive delimiters`,
         };
     }
     return { name };
 }
-/**
- * Validates an already-`JSON.parse`d `plugin.json` value against the 1.0.0/1.1.0 grammar.
- *
- * @throws Nothing — every failure is reported via the returned `errors`, matching this codebase's
- * own convention for expected validation outcomes (`plugin-runtime/manifest.ts`,
- * `plugin-runtime/discovery.ts`).
- * @complexity O(k + n) time and space in the input keys and keyword entries.
- */
-export function parseAgentPluginManifest({ value }, { identityNamespace = "tovu" } = {}) {
-    if (!isJsonObject(value))
-        return { ok: false, errors: ["plugin.json must be a JSON object"] };
-    const raw = value;
+/** Every `plugin.json` error and warning, in report order: spec version, extensions, name, unknown keys, identity. */
+function collectManifestProblems({ raw, identityNamespace }, { nameError } = {}) {
     const errors = [];
     const warnings = [];
     const specVersion = readSpecVersion(raw.$schema, "plugin");
@@ -169,19 +176,39 @@ export function parseAgentPluginManifest({ value }, { identityNamespace = "tovu"
         warnings.push(specVersion.warning);
     if (raw.extensions !== undefined && !isJsonObject(raw.extensions))
         errors.push("plugin.json extensions must be an object");
-    const nameResult = resolveManifestName(raw);
-    if (nameResult.error)
-        errors.push(nameResult.error);
+    if (nameError)
+        errors.push(nameError);
     for (const key of Object.keys(raw)) {
         if (!KNOWN_MANIFEST_KEYS.has(key))
             warnings.push(`unrecognized plugin.json field '${key}' (ignored per spec)`);
     }
     errors.push(...validatePluginIdentity({ manifest: raw, namespace: identityNamespace }).errors);
+    return { errors, warnings };
+}
+/**
+ * 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`,
+ * `plugin-runtime/discovery.ts`).
+ * @complexity O(k + n) time and space in the input keys and keyword entries.
+ */
+export function parseAgentPluginManifest({ value }, { identityNamespace = "tovu" } = {}) {
+    if (!isJsonObject(value))
+        return { ok: false, errors: ["plugin.json must be a JSON object"] };
+    const raw = value;
+    const nameResult = resolveManifestName(raw);
+    const { errors, warnings } = collectManifestProblems({ raw, identityNamespace }, { nameError: nameResult.error });
     if (errors.length > 0)
         return { ok: false, errors };
     const identity = readPluginIdentity({ manifest: raw, namespace: identityNamespace });
     warnings.push(...identity.warnings);
+    const extension = isJsonObject(raw.extensions) && isJsonObject(raw.extensions[identityNamespace]) ? raw.extensions[identityNamespace] : {};
+    const { warnings: compatibilityWarnings, ...compatibility } = readAgentPluginCompatibilityMetadata({ extension });
+    warnings.push(...compatibilityWarnings);
     const manifest = {
+        ...compatibility,
         name: nameResult.name,
         id: identity.id,
         provides: identity.provides,
@@ -223,20 +250,12 @@ function isStringRecord(value) {
 function parseStdioServerConfig(raw) {
     if (typeof raw.command !== "string" || raw.command.length === 0)
         return null;
-    const { args, env, cwd } = raw;
-    if (args !== undefined && !(Array.isArray(args) && args.every((entry) => typeof entry === "string")))
-        return null;
-    if (env !== undefined && (!isStringRecord(env) || RESERVED_STDIO_ENV_KEYS.some((key) => Object.hasOwn(env, key))))
-        return null;
-    if (cwd !== undefined && typeof cwd !== "string")
+    const args = parseOptional({ value: raw.args, parse: (value) => Array.isArray(value) && value.every((entry) => typeof entry === "string") ? value : null });
+    const env = parseOptional({ value: raw.env, parse: (value) => isStringRecord(value) && !RESERVED_STDIO_ENV_KEYS.some((key) => Object.hasOwn(value, key)) ? value : null });
+    const cwd = parseOptional({ value: raw.cwd, parse: (value) => typeof value === "string" ? value : null });
+    if (args === null || env === null || cwd === null)
         return null;
-    return {
-        type: "stdio",
-        command: raw.command,
-        ...(args !== undefined ? { args: args } : {}),
-        ...(env !== undefined ? { env } : {}),
-        ...(cwd !== undefined ? { cwd } : {}),
-    };
+    return { type: "stdio", command: raw.command, ...definedFields({ args, env, cwd }) };
 }
 /**
  * Same bound and grammar as `external-mcp-store.ts`'s `MAX_ALLOWED_TOOLS`/`REMOTE_TOOL_NAME_PATTERN`,
@@ -252,6 +271,10 @@ function parseDefaultToolNames(value) {
         return null;
     return value.every((name) => typeof name === "string" && DEFAULT_TOOL_NAME_PATTERN.test(name)) ? value : null;
 }
+/** `read` and `write` default to `[]` when absent. */
+function parseGrantList(value) {
+    return value === undefined ? [] : parseDefaultToolNames(value);
+}
 /**
  * Validates bounded sign-in and read lists. `read` and `write` default to `[]`.
  * A provided `allow` bounds both lists; without it only a read declaration is meaningful,
@@ -263,15 +286,15 @@ function parseDefaultToolNames(value) {
 function parseDefaultTools(value) {
     if (!isJsonObject(value))
         return null;
-    const allow = value.allow === undefined ? undefined : parseDefaultToolNames(value.allow);
-    const write = value.write === undefined ? [] : parseDefaultToolNames(value.write);
-    const read = value.read === undefined ? [] : parseDefaultToolNames(value.read);
+    const allow = parseOptional({ value: value.allow, parse: parseDefaultToolNames });
+    const write = parseGrantList(value.write);
+    const read = parseGrantList(value.read);
     if (allow === null || write === null || read === null)
         return null;
     if (allow === undefined)
         return value.read !== undefined && write.length === 0 ? { write, read } : null;
     const allowed = new Set(allow);
-    return write.every((name) => allowed.has(name)) && read.every((name) => allowed.has(name)) ? { allow, write, read } : null;
+    return [...write, ...read].every((name) => allowed.has(name)) ? { allow, write, read } : null;
 }
 const MAX_TOKEN_AUTH_URL_LENGTH = 2048;
 function isHttpsUrl(value) {
@@ -319,18 +342,11 @@ function parseRenamedTools(value) {
 function parseTokenAuth(value) {
     if (!isJsonObject(value) || !isHttpsUrl(value.helpUrl) || !isHttpsUrl(value.probeUrl))
         return null;
-    const { importFromEnv } = value;
-    if (importFromEnv !== undefined && !isEnvVarName(importFromEnv))
-        return null;
-    const retiredEnv = value.retiredEnv === undefined ? undefined : parseRetiredEnv(value.retiredEnv);
-    if (retiredEnv === null)
+    const importFromEnv = parseOptional({ value: value.importFromEnv, parse: (name) => isEnvVarName(name) ? name : null });
+    const retiredEnv = parseOptional({ value: value.retiredEnv, parse: parseRetiredEnv });
+    if (importFromEnv === null || retiredEnv === null)
         return null;
-    return {
-        helpUrl: value.helpUrl,
-        probeUrl: value.probeUrl,
-        ...(importFromEnv !== undefined ? { importFromEnv } : {}),
-        ...(retiredEnv !== undefined ? { retiredEnv } : {}),
-    };
+    return { helpUrl: value.helpUrl, probeUrl: value.probeUrl, ...definedFields({ importFromEnv, retiredEnv }) };
 }
 /**
  * Validates one `type: "streamable-http"` or `type: "sse"` server entry — the two remote transports
@@ -345,45 +361,64 @@ function parseTokenAuth(value) {
 function parseRemoteServerConfig(type, raw, extension) {
     if (typeof raw.url !== "string" || raw.url.length === 0)
         return null;
-    const { headers } = raw;
-    const authMode = extension?.authMode;
-    if (headers !== undefined && !isStringRecord(headers))
-        return null;
-    if (authMode !== undefined && authMode !== "oauth" && authMode !== "none")
+    const headers = parseOptional({ value: raw.headers, parse: (value) => isStringRecord(value) ? value : null });
+    const metadata = parseServerMetadata(extension ?? {});
+    if (headers === null || metadata === null)
         return null;
-    const defaults = extension?.defaultTools;
-    const defaultTools = defaults === undefined ? undefined : parseDefaultTools(defaults);
-    if (defaultTools === null)
-        return null;
-    const tokenAuth = extension?.tokenAuth === undefined ? undefined : parseTokenAuth(extension?.tokenAuth);
-    if (tokenAuth === null)
-        return null;
-    const renamedTools = extension?.renamedTools === undefined ? undefined : parseRenamedTools(extension?.renamedTools);
-    if (renamedTools === null)
+    return { type, url: raw.url, ...definedFields({ headers }), ...metadata };
+}
+/** A remote entry's extension metadata, or `null` when any declared member is malformed. */
+function parseServerMetadata(extension) {
+    const authMode = parseOptional({ value: extension.authMode, parse: (mode) => mode === "oauth" || mode === "none" ? mode : null });
+    const defaultTools = parseOptional({ value: extension.defaultTools, parse: parseDefaultTools });
+    const tokenAuth = parseOptional({ value: extension.tokenAuth, parse: parseTokenAuth });
+    const renamedTools = parseOptional({ value: extension.renamedTools, parse: parseRenamedTools });
+    if (authMode === null || defaultTools === null || tokenAuth === null || renamedTools === null)
         return null;
-    return {
-        type,
-        url: raw.url,
-        ...(headers !== undefined ? { headers } : {}),
-        ...(authMode !== undefined ? { authMode } : {}),
-        ...(defaultTools !== undefined ? { defaultTools } : {}),
-        ...(tokenAuth !== undefined ? { tokenAuth } : {}),
-        ...(renamedTools !== undefined ? { renamedTools } : {}),
-    };
+    return definedFields({ authMode, defaultTools, tokenAuth, renamedTools });
 }
 /**
- * Dispatches one raw `mcpServers` entry to its transport's validator by `type`, or `null` for a
- *  non-object entry or a `type` outside {@link MCP_SERVER_TRANSPORTS}.
+ * Dispatches one `mcpServers` object entry to its transport's validator by `type`, or `null` for a
+ *  `type` outside {@link MCP_SERVER_TRANSPORTS}.
  */
 function parseMcpServerConfig(value, extension) {
-    if (!isJsonObject(value))
-        return null;
     if (value.type === "stdio")
         return parseStdioServerConfig(value);
     if (value.type === "streamable-http" || value.type === "sse")
         return parseRemoteServerConfig(value.type, value, extension);
     return null;
 }
+/** One declared server, or `null` for a non-object entry, a malformed extension, or an invalid transport shape. */
+function parseDeclaredServer({ serverId, rawServer, extension }, { readServerMetadata } = {}) {
+    // A malformed declared extension excludes the server before the translator can hide it.
+    if (!isJsonObject(rawServer) || (extension !== undefined && !isJsonObject(extension)))
+        return null;
+    const metadata = readServerMetadata?.({ serverId, value: extension ?? {}, server: rawServer }) ?? extension;
+    return parseMcpServerConfig(rawServer, metadata);
+}
+/** `mcp.json`'s top-level errors: its own `$schema`, a version mismatch with `plugin.json` (§10), and `mcpServers`' shape. */
+function collectMcpConfigErrors({ raw }, { pluginManifest } = {}) {
+    const errors = [];
+    // plugin.json already reports an unknown-1.x warning; mcp.json adds none of its own.
+    const mcpSpec = readSpecVersion(raw.$schema, "mcp");
+    const mcpVersion = mcpSpec.version;
+    const pluginVersion = isJsonObject(pluginManifest) ? readSpecVersion(pluginManifest.$schema, "plugin").version : undefined;
+    if (mcpSpec.error)
+        errors.push(mcpSpec.error);
+    else if (pluginVersion !== undefined && pluginVersion !== mcpVersion) {
+        errors.push(`mcp.json targets Agent Plugins ${mcpVersion} but plugin.json targets ${pluginVersion}; the versions must match`);
+    }
+    if (!isJsonObject(raw.mcpServers))
+        errors.push("mcp.json 'mcpServers' is required and must be an object");
+    return errors;
+}
+/** The per-server metadata `plugin.json` declares under `extensionNamespace`, or `{}` when it declares none. */
+function readExtensionServers({ pluginManifest, extensionNamespace }) {
+    const manifest = parseAgentPluginManifest({ value: pluginManifest });
+    if (!manifest.ok)
+        return {};
+    return readAgentPluginExtension({ manifest: manifest.manifest, namespace: extensionNamespace, read: ({ value }) => isJsonObject(value.mcpServers) ? value.mcpServers : {} }) ?? {};
+}
 /**
  * Validates an already-`JSON.parse`d `mcp.json` value against the 1.0.0/1.1.0 top-level shape:
  * `{ "$schema": ..., "mcpServers": { "<server-id>": {...} } }`, then validates each declared
@@ -398,35 +433,15 @@ export function parseAgentPluginMcpConfig({ value, extensionNamespace }, optiona
         throw new Error("An extension namespace is required");
     if (!isJsonObject(value))
         return { ok: false, errors: ["mcp.json must be a JSON object"] };
-    const raw = value;
-    const errors = [];
-    // plugin.json already reports an unknown-1.x warning; mcp.json adds none of its own.
-    const mcpSpec = readSpecVersion(raw.$schema, "mcp");
-    const mcpVersion = mcpSpec.version;
-    const pluginVersion = isJsonObject(optional.pluginManifest) ? readSpecVersion(optional.pluginManifest.$schema, "plugin").version : undefined;
-    if (mcpSpec.error)
-        errors.push(mcpSpec.error);
-    else if (pluginVersion !== undefined && pluginVersion !== mcpVersion) {
-        errors.push(`mcp.json targets Agent Plugins ${mcpVersion} but plugin.json targets ${pluginVersion}; the versions must match`);
-    }
-    const mcpServers = raw.mcpServers;
-    if (typeof mcpServers !== "object" || mcpServers === null || Array.isArray(mcpServers)) {
-        errors.push("mcp.json 'mcpServers' is required and must be an object");
-    }
+    const errors = collectMcpConfigErrors({ raw: value }, { pluginManifest: optional.pluginManifest });
     if (errors.length > 0)
         return { ok: false, errors };
-    const manifest = parseAgentPluginManifest({ value: optional.pluginManifest });
-    const extension = manifest.ok ? readAgentPluginExtension({ manifest: manifest.manifest, namespace: extensionNamespace, read: ({ value }) => isJsonObject(value.mcpServers) ? value.mcpServers : {} }) : undefined;
-    const extensionServers = extension ?? {};
-    const entries = Object.entries(mcpServers);
+    const extensionServers = readExtensionServers({ pluginManifest: optional.pluginManifest, extensionNamespace });
+    const entries = Object.entries(value.mcpServers);
     const servers = Object.create(null);
     for (const [serverId, rawServer] of entries) {
         const extension = Object.hasOwn(extensionServers, serverId) ? extensionServers[serverId] : undefined;
-        // A malformed declared extension excludes the server before the translator can hide it.
-        const metadata = isJsonObject(rawServer) && (extension === undefined || isJsonObject(extension))
-            ? optional.readServerMetadata?.({ serverId, value: extension ?? {}, server: rawServer }) ?? extension
-            : undefined;
-        const parsed = extension !== undefined && !isJsonObject(extension) ? null : parseMcpServerConfig(rawServer, metadata);
+        const parsed = parseDeclaredServer({ serverId, rawServer, extension }, { readServerMetadata: optional.readServerMetadata });
         if (parsed)
             servers[serverId] = parsed;
     }

package/dist/lifecycle/package-paths.js

@@ -81,10 +81,10 @@ function buildModule(ports) {
     async function assertContainedOnDisk(packageRoot, entryPath) {
         const normalized = normalizePackageEntryPath(entryPath);
         const realRoot = await realpath(packageRoot);
+        // No separate lexical-escape check: normalizePackageEntryPath already refused absolute, drive-
+        // letter and `..`-leading paths, so resolving its relative output always stays under realRoot,
+        // and the filesystem-resolved check below would refuse any escape regardless.
         const lexicalCandidate = path.resolve(realRoot, normalized);
-        if (!isWithin(realRoot, lexicalCandidate)) {
-            throw new PackagePathViolation({ message: `package entry resolves outside the package root: '${entryPath}'` });
-        }
         let realCandidate;
         try {
             realCandidate = await realpath(lexicalCandidate);

package/dist/lifecycle/ports.d.ts

@@ -4,7 +4,7 @@ import type { AgentPluginLayoutPort } from './layout.js';
 import type { AgentPluginDeliveryMode, InstalledAgentPlugin } from './types.js';
 /** Native Node filesystem ABI, narrowed to the operations used by lifecycle.
  * Inject instrumented fs/promises effects directly; native handles are never rewrapped. */
-export type FilesystemPort = Pick<typeof import('node:fs/promises'), 'chmod' | 'mkdir' | 'mkdtemp' | 'open' | 'readdir' | 'readFile' | 'rename' | 'rm' | 'rmdir' | 'stat' | 'realpath' | 'unlink'>;
+export type FilesystemPort = Pick<typeof import('node:fs/promises'), 'chmod' | 'mkdir' | 'mkdtemp' | 'open' | 'readdir' | 'readFile' | 'rename' | 'rm' | 'rmdir' | 'stat' | 'lstat' | 'realpath' | 'unlink'>;
 export type AgentPluginFetchPort = (required: {
     readonly url: string;
 }, optional?: RequestInit) => Promise<Response>;