@jini-ai/agent-plugins 0.4.3 → 0.4.4

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.4.4 — 2026-10-12 — Agent Plugins 1.1.0
+
+- `parseAgentPluginManifest()` / `parseAgentPluginMcpConfig()` (and so the installer and MCP
+  projection) select the grammar by `$schema` and accept Agent Plugins 1.1.0 identifiers alongside
+  1.0.0. 1.1.0 changes only the version identifiers, so both map to the same validator; 1.0.0
+  behavior is unchanged. When a `plugin.json` is supplied, `mcp.json` must target the same version
+  (§10).
+- Forward-compatible within major 1 (owner decision): an unknown 1.x (e.g. 1.2.0) is validated with
+  the newest known (1.1.0) grammar and reports one warning naming the version. A different major
+  (2.x, 0.x) is refused as an unsupported major version; a non-canonical `$schema` is refused with
+  the accepted identifiers listed.
+
 ## 0.4.2
 
 - Use shared plugin identity metadata with a required `@jini-ai/core` peer at `^0.4.2`. Repair identity-lock publication syntax and isolate unreadable or invalid installed manifests with warnings so one damaged install cannot block healthy installs or bundled seeding.

package/README.md

@@ -2,9 +2,9 @@
 
 > **Leon, this is you from the past. Do not try to merge `plugins` and `agent-plugins`.**
 
-Support for **Agent Plugins**, an open, vendor-neutral spec (v1.0.0, published 2026-08-06) for
-bundling Agent Skills and MCP servers into one portable directory. Published by a Technical
-Steering Committee with maintainers from Amazon, Cursor, Google, Microsoft, OpenAI, and Vercel.
+Support for **Agent Plugins**, an open, vendor-neutral spec (v1.0.0, published 2026-08-06; v1.1.0 and
+later 1.x manifests are also accepted) for bundling Agent Skills and MCP servers into one portable
+directory. Published by a Technical Steering Committee with maintainers from Amazon, Cursor, Google, Microsoft, OpenAI, and Vercel.
 Source: https://developers.googleblog.com/agent-plugins-package-your-skills-tools-and-more/
 
 If you are an agent reading this cold: this document is written so you don't need the source

package/dist/lifecycle/manifest.d.ts

@@ -2,7 +2,7 @@ export { validatePluginManifest, validateMcpManifest } from '../manifest.js';
 export type { PluginManifest, McpManifest, McpServerEntry } from '../manifest.js';
 import type { PluginManifestAuthor } from '../manifest.js';
 export type { PluginManifestAuthor } from '../manifest.js';
-/** Agent Plugins 1.0.0 parsing, with application metadata confined to an explicit namespace. */
+/** Agent Plugins 1.0.0/1.1.0 parsing, with application metadata confined to an explicit namespace. */
 export type AgentPluginServerMetadataReader = (required: {
     readonly serverId: string;
     readonly value: Readonly<Record<string, unknown>>;
@@ -29,7 +29,7 @@ export type ParseAgentPluginManifestResult = {
     readonly errors: readonly string[];
 };
 /**
- * Validates an already-`JSON.parse`d `plugin.json` value against the v1.0.0 grammar.
+ * 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`,
@@ -42,7 +42,7 @@ export declare function parseAgentPluginManifest({ value }: {
     readonly identityNamespace?: string;
 }): ParseAgentPluginManifestResult;
 /**
- * The three closed transport variants `mcp.schema.json` v1.0.0 defines. See this file's header for
+ * The three closed transport variants `mcp.schema.json` 1.0.0/1.1.0 defines. See this file's header for
  * the verified field shape of each.
  */
 export declare const MCP_SERVER_TRANSPORTS: readonly ["stdio", "streamable-http", "sse"];
@@ -134,9 +134,10 @@ export type ParseAgentPluginMcpConfigResult = {
     readonly errors: readonly string[];
 };
 /**
- * Validates an already-`JSON.parse`d `mcp.json` value against the v1.0.0 top-level shape:
+ * 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
- * server's own transport shape (see this file's header for the three variants).
+ * server's own transport shape (see this file's header for the three variants). When
+ * `pluginManifest` declares a supported version, `mcp.json` must declare the same one (§10).
  *
  * @throws Nothing — see {@link parseAgentPluginManifest}.
  * @complexity O(s) in the number of declared servers.

package/dist/lifecycle/manifest.js

@@ -1,5 +1,5 @@
 /**
- * @file `parseAgentPluginManifest()` / `parseAgentPluginMcpConfig()` — the Agent Plugins v1.0.0
+ * @file `parseAgentPluginManifest()` / `parseAgentPluginMcpConfig()` — the Agent Plugins 1.0.0/1.1.0
  * `plugin.json` / `mcp.json` grammar (agent-plugins.org/specification), verified against the live
  * spec rather than inferred from an example manifest.
  *
@@ -10,13 +10,15 @@
  * shares none of those fields and defines no execution/trust/capability model at all — see this
  * feature's own header comment in `install.ts` for why the two formats cannot be unified.
  *
- * Pinned v1.0.0 rules from agent-plugins.org/specification:
+ * Pinned 1.0.0/1.1.0 rules from agent-plugins.org/specification:
  * - `plugin.json`'s `name`: 1-64 chars, lowercase alphanumeric/hyphen/period only, must start and
  *   end alphanumeric, no `--` or `..` consecutive delimiters (§5.5). Valid: `my-plugin`,
  *   `acme.tools`, `lint3r`, `a`. Invalid: `My-Plugin`, `-start`, `has--double`.
- * - `plugin.json`'s `$schema` MUST equal `https://agent-plugins.org/schemas/1.0.0/plugin.schema.json`
- *   for this pinned version; `mcp.json`'s MUST equal
- *   `https://agent-plugins.org/schemas/1.0.0/mcp.schema.json`.
+ * - `plugin.json`'s `$schema` MUST be a recognized canonical identifier
+ *   (`https://agent-plugins.org/schemas/<version>/plugin.schema.json`); `mcp.json`'s likewise
+ *   (`.../<version>/mcp.schema.json`), and when both are present their versions MUST match (§10).
+ *   1.0.0 and 1.1.0 are recognized; an unknown 1.x is read with the newest known grammar plus one
+ *   warning; any other major is refused — see `KNOWN_SPEC_VERSIONS`.
  * - Unknown top-level `plugin.json` fields produce warnings but do not block loading — this module
  *   returns them as `warnings`, never as a rejection reason.
  * - `mcp.json`'s top-level shape is `{ "$schema": ..., "mcpServers": { "<server-id>": {...} } }` —
@@ -55,11 +57,44 @@
 import { readPluginIdentity, validatePluginIdentity } from "@jini-ai/core/plugin-directory";
 export { validatePluginManifest, validateMcpManifest } from '../manifest.js';
 /**
- * The one plugin.json schema version this loader understands. A manifest declaring any other
- * value is rejected outright rather than guessed at: pinning the grammar must survive spec churn.
+ * The Agent Plugins versions whose schemas have been diffed against this file's grammar. 1.1.0's
+ * spec text and both schemas differ from 1.0.0 only in the version identifiers, so both map to the
+ * one grammar below — §5.1 allows mapping explicitly recognized compatible versions to one
+ * implementation. Add a version here only after diffing its schemas against this grammar.
  */
-const PLUGIN_SCHEMA_1_0_0 = "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json";
-const MCP_SCHEMA_1_0_0 = "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json";
+const KNOWN_SPEC_VERSIONS = ["1.0.0", "1.1.0"];
+const SUPPORTED_MAJOR = "1";
+/**
+ * Owner decision (2026-10-12): any other 1.x is accepted with the newest known grammar and one
+ * warning, so a minor spec release does not lock out packages that target it. This goes beyond
+ * §5.1, which says a client MUST reject a version it does not explicitly recognize. Unknown fields
+ * stay tolerated only where the known grammar already allows them (unknown top-level fields warn,
+ * `extensions` is opaque). A different major is refused, since majors may break the grammar.
+ */
+const SCHEMA_URL_PATTERN = /^https:\/\/agent-plugins\.org\/schemas\/((\d+)\.\d+\.\d+)\/(plugin|mcp)\.schema\.json$/;
+/** The canonical `$schema` identifier for one spec version's `plugin.json` or `mcp.json`. */
+function schemaUrl(version, file) {
+    return `https://agent-plugins.org/schemas/${version}/${file}.schema.json`;
+}
+/**
+ * Reads the spec version `value` names as `file`'s canonical schema identifier: a known version,
+ * an unknown 1.x (with its warning), or the error for a different major or a non-canonical value.
+ */
+function readSpecVersion(value, file) {
+    const match = typeof value === "string" ? SCHEMA_URL_PATTERN.exec(value) : null;
+    if (!match || match[3] !== file) {
+        const accepted = KNOWN_SPEC_VERSIONS.map((version) => `'${schemaUrl(version, file)}'`).join(" or ");
+        return { error: `${file}.json '$schema' must be ${accepted} (Agent Plugins ${KNOWN_SPEC_VERSIONS.join(", ")}, or another ${SUPPORTED_MAJOR}.x), got '${String(value)}'` };
+    }
+    const version = match[1];
+    if (match[2] !== SUPPORTED_MAJOR) {
+        return { error: `${file}.json targets Agent Plugins ${version}, an unsupported major version (supported: ${SUPPORTED_MAJOR}.x)` };
+    }
+    if (KNOWN_SPEC_VERSIONS.includes(version))
+        return { version };
+    const newest = KNOWN_SPEC_VERSIONS[KNOWN_SPEC_VERSIONS.length - 1];
+    return { version, warning: `${file}.json targets Agent Plugins ${version}, newer than this loader knows; validated with the ${newest} grammar` };
+}
 /**
  * §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
@@ -114,7 +149,7 @@ function resolveManifestName(raw) {
     return { name };
 }
 /**
- * Validates an already-`JSON.parse`d `plugin.json` value against the v1.0.0 grammar.
+ * 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`,
@@ -127,9 +162,11 @@ export function parseAgentPluginManifest({ value }, { identityNamespace = "tovu"
     const raw = value;
     const errors = [];
     const warnings = [];
-    if (raw.$schema !== PLUGIN_SCHEMA_1_0_0) {
-        errors.push(`plugin.json '$schema' must be '${PLUGIN_SCHEMA_1_0_0}', got '${String(raw.$schema)}'`);
-    }
+    const specVersion = readSpecVersion(raw.$schema, "plugin");
+    if (specVersion.error)
+        errors.push(specVersion.error);
+    else if (specVersion.warning)
+        warnings.push(specVersion.warning);
     if (raw.extensions !== undefined && !isJsonObject(raw.extensions))
         errors.push("plugin.json extensions must be an object");
     const nameResult = resolveManifestName(raw);
@@ -158,7 +195,7 @@ export function parseAgentPluginManifest({ value }, { identityNamespace = "tovu"
     return { ok: true, manifest, warnings };
 }
 /**
- * The three closed transport variants `mcp.schema.json` v1.0.0 defines. See this file's header for
+ * The three closed transport variants `mcp.schema.json` 1.0.0/1.1.0 defines. See this file's header for
  * the verified field shape of each.
  */
 export const MCP_SERVER_TRANSPORTS = ["stdio", "streamable-http", "sse"];
@@ -348,9 +385,10 @@ function parseMcpServerConfig(value, extension) {
     return null;
 }
 /**
- * Validates an already-`JSON.parse`d `mcp.json` value against the v1.0.0 top-level shape:
+ * 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
- * server's own transport shape (see this file's header for the three variants).
+ * server's own transport shape (see this file's header for the three variants). When
+ * `pluginManifest` declares a supported version, `mcp.json` must declare the same one (§10).
  *
  * @throws Nothing — see {@link parseAgentPluginManifest}.
  * @complexity O(s) in the number of declared servers.
@@ -362,8 +400,14 @@ export function parseAgentPluginMcpConfig({ value, extensionNamespace }, optiona
         return { ok: false, errors: ["mcp.json must be a JSON object"] };
     const raw = value;
     const errors = [];
-    if (raw.$schema !== MCP_SCHEMA_1_0_0) {
-        errors.push(`mcp.json '$schema' must be '${MCP_SCHEMA_1_0_0}', got '${String(raw.$schema)}'`);
+    // 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)) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jini-ai/agent-plugins",
-  "version": "0.4.3",
-  "description": "Support for Agent Plugins, the open, vendor-neutral spec (v1.0.0, published 2026-08-06, 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.",
+  "version": "0.4.4",
+  "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": {
     "type": "git",