@jini-ai/agent-plugins 0.4.2 → 0.4.3

package/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## 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.
+
 ### Patch Changes
 
 - Tovu clean-up release (2026-10-08): code Tovu moved into Jini, plus the Jini clean-up (see the commit log since 0.4.1).

package/dist/lifecycle/bundled-digests.js

@@ -3,6 +3,10 @@
  * ships as — written by `seed-bundled.ts` on every boot, read by the surfaces that have to pick one
  * installed package for a plugin id.
  *
+ * Current install policy (frpid, 2026-10-09): successful publication prunes superseded revisions.
+ * The rationale below describes retained legacy stores and interrupted cleanup. This ledger still
+ * selects the build's authoritative digest there; the ledger itself never deletes package bytes.
+ *
  * ---------------------------------------------------------------------------
  * The gap this closes
  * ---------------------------------------------------------------------------

package/dist/lifecycle/install.d.ts

@@ -5,7 +5,7 @@ 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 = "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 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 }: {

package/dist/lifecycle/install.js

@@ -1,3 +1,6 @@
+import { listInstalledPackageRoots } from "./installed-package-roots.js";
+import { createUninstallModule } from "./uninstall.js";
+import { readPluginIdentity, assertPluginIdentityAvailable } from "@jini-ai/core/plugin-directory";
 /**
  * @file `installAgentPlugin()` — content-addressed, adversarially-hardened extraction of one Agent
  * Plugin (agent-plugins.org) archive into one workspace's own `AgentPluginWorkspaceLayout.packages`.
@@ -95,7 +98,7 @@ 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 });
+    const parseAgentPluginManifest = (value) => parseAgentPluginManifestValue({ value }, { identityNamespace: ports.extensionNamespace });
     const { assertContainedOnDisk, normalizePackageEntryPath } = createPackagePathsModule(ports);
     const LIMITS = {
         maxArchiveBytes: 32 * 1024 * 1024,
@@ -103,6 +106,63 @@ function buildModule(ports) {
         maxFileBytes: 16 * 1024 * 1024,
         maxTotalExtractedBytes: 64 * 1024 * 1024,
     };
+    /** Publisher ids are metadata, never filesystem segments. The workspace identity lock
+     * serializes installs under different local names competing for one qualified id.
+     * @complexity O(d) manifest reads for d installed revisions; no executable imports. */
+    async function assertIdentityAvailable(workspaceRoot, candidate) {
+        // Installed roots are canonical paths; compare against the same root even when the host
+        // supplied an OS alias (macOS /var -> /private/var). Containment still rejects escaped links.
+        workspaceRoot = await ports.filesystem.realpath(workspaceRoot);
+        for (const root of await listInstalledPackageRoots({ ports, workspaceRoot })) {
+            const manifestPath = path.join(root.packageRoot, 'plugin.json');
+            await persistentState.assertOwnedPath({ workspaceRoot, entryPath: path.relative(workspaceRoot, manifestPath) });
+            let raw;
+            let identity;
+            try {
+                raw = JSON.parse(await readFile(manifestPath, 'utf8'));
+                identity = readPluginIdentity({ manifest: raw, name: root.localId, namespace: ports.extensionNamespace });
+            }
+            catch {
+                // A damaged unrelated install must not block fresh installs or bundled seeding.
+                ports.onEvent?.({ event: 'agent-plugin-identity-warning', message: `Plugin '${root.localId}': installed identity manifest is unreadable or invalid; omitted from identity admission.` });
+                continue;
+            }
+            try {
+                assertPluginIdentityAvailable({ candidate: { id: candidate.id, localId: candidate.pluginId, family: 'agent-plugin' },
+                    installed: [{ ...identity, localId: root.localId, family: 'agent-plugin', version: typeof raw.version === 'string' ? raw.version : null, enabled: false }] });
+            }
+            catch {
+                throw new AgentPluginInstallError({ code: 'PLUGIN_ID_CONFLICT', message: 'The publisher-qualified plugin id conflicts with an installed package.' });
+            }
+        }
+    }
+    /** Retires only this plugin's superseded revisions after accepted publication, under the same
+     * identity/plugin locks. Persistent data, learned facts and notes never enter this operation.
+     * Reuse uninstall's frozen-tree staging so an interrupted removal is no longer a live digest.
+     * There is no previous-revision rollback slot in this lifecycle; failed publication keeps all
+     * prior bytes. Cleanup faults warn without turning an accepted install into a failed install.
+     * @complexity O(d + f), d workspace revisions, f files in this plugin's superseded packages.
+     */
+    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)
+                    continue;
+                try {
+                    const staged = await removal.stageForRemoval(path.dirname(root.packageRoot), root.packageRoot);
+                    await removal.removeFrozenPackageTree(staged.quarantined);
+                }
+                catch {
+                    ports.onEvent?.({ event: 'agent-plugin-revision-prune-warning', message: `Plugin '${installed.pluginId}': a superseded revision could not be pruned.` });
+                }
+            }
+        }
+        catch {
+            ports.onEvent?.({ event: 'agent-plugin-revision-prune-warning', message: `Plugin '${installed.pluginId}': superseded revisions could not be scanned for pruning.` });
+        }
+    }
     /** Exposes `LIMITS.maxArchiveBytes` for a caller outside this module — concretely, a test asserting
    * `@jini-ai/agent-plugins/lifecycle`'s fetch cap constant stays pinned to this one. The local fetch-archive.ts fork was deleted; see the package's fetch module
    * for why it duplicates the number instead of importing it (no runtime dependency on `install.ts`);
@@ -150,43 +210,56 @@ function buildModule(ports) {
             const indexed = await indexInstalledRoot(extractionRoot, digest);
             if (optional.previewOnly)
                 return indexed;
-            return await persistentState.withPluginLock({ workspaceRoot: workspaceLayout.root, pluginId: indexed.pluginId, run: async () => {
-                    // Layout B needs the manifest id before choosing the package destination. Dedup still
-                    // skips publication and freezing, after one bounded staging extraction.
-                    // Owner decision 2026-10-04: learned facts begin empty for each site; author guidance stays
-                    // in package docs. Package extension files never seed learned memory or the user's notes.
-                    // Content-addressed dedup, scoped to THIS workspace's own tree (`workspaceLayout` was just
-                    // resolved above, atomically, from this same `workspaceId`): identical bytes were already
-                    // extracted, verified, and frozen by a prior install of this same workspace's — never
-                    // re-extracted for a different workspace, by construction, since a different workspace's
-                    // `workspaceLayout.packages` is a different path entirely. one bounded staging extraction precedes this check.
-                    // Publish BEFORE freezing permissions, not after: `rename()` moves `extractionRoot` as a single
-                    // directory-entry operation, and on this filesystem renaming an already-read-only (0o555)
-                    // directory itself fails EACCES (observed, not merely theoretical — see the regression test this
-                    // ordering fixed). Freezing after publish also closes a smaller race for free: nothing outside
-                    // this function can observe the package at its live path while it is still writable, because the
-                    // live path does not exist until `publish` returns.
-                    const publishPackage = async () => {
-                        // The manifest identifies the plugin only after bounded staging extraction (Layout B).
-                        const pluginId = indexed.pluginId;
-                        const packagesDir = workspaceLayout.pluginPackagesDir({ pluginId });
-                        await persistentState.assertOwnedPath({ workspaceRoot: workspaceLayout.root, entryPath: path.relative(workspaceLayout.root, packagesDir) });
-                        await mkdir(packagesDir, { recursive: true, mode: 0o700 });
-                        const finalRoot = await assertContainedOnDisk(packagesDir, digest);
-                        for (const directory of [workspaceLayout.pluginDataDir({ pluginId }),
-                            workspaceLayout.pluginMemoryDir({ pluginId, kind: 'learned' }),
-                            workspaceLayout.pluginMemoryDir({ pluginId, kind: 'notes' })]) {
-                            await persistentState.assertOwnedPath({ workspaceRoot: workspaceLayout.root, entryPath: path.relative(workspaceLayout.root, directory) });
-                            await mkdir(directory, { recursive: true, mode: 0o700 });
-                        }
-                        if (await isRealDirectory(finalRoot))
-                            return indexInstalledRoot(finalRoot, digest);
-                        await publish(extractionRoot, finalRoot);
-                        await freezeTree(finalRoot, executablePaths);
-                        /** Absolute, read-only (frozen) path to the extracted package root. */
-                        return { ...indexed, packageRoot: finalRoot };
-                    };
-                    return optional.publishGuard ? optional.publishGuard({ plugin: indexed, publish: publishPackage }, {}) : publishPackage();
+            return await persistentState.withIdentityLock({ workspaceRoot: workspaceLayout.root, run: async () => {
+                    await assertIdentityAvailable(workspaceLayout.root, indexed);
+                    const publishWithinPluginLock = () => persistentState.withPluginLock({ workspaceRoot: workspaceLayout.root, pluginId: indexed.pluginId, run: async () => {
+                            // Layout B needs the manifest id before choosing the package destination. Dedup still
+                            // skips publication and freezing, after one bounded staging extraction.
+                            // Owner decision 2026-10-04: learned facts begin empty for each site; author guidance stays
+                            // in package docs. Package extension files never seed learned memory or the user's notes.
+                            // Content-addressed dedup, scoped to THIS workspace's own tree (`workspaceLayout` was just
+                            // resolved above, atomically, from this same `workspaceId`): identical bytes were already
+                            // extracted, verified, and frozen by a prior install of this same workspace's — never
+                            // re-extracted for a different workspace, by construction, since a different workspace's
+                            // `workspaceLayout.packages` is a different path entirely. one bounded staging extraction precedes this check.
+                            // Publish BEFORE freezing permissions, not after: `rename()` moves `extractionRoot` as a single
+                            // directory-entry operation, and on this filesystem renaming an already-read-only (0o555)
+                            // directory itself fails EACCES (observed, not merely theoretical — see the regression test this
+                            // ordering fixed). Freezing after publish also closes a smaller race for free: nothing outside
+                            // this function can observe the package at its live path while it is still writable, because the
+                            // live path does not exist until `publish` returns.
+                            let publishedPlugin;
+                            const publishPackage = async () => {
+                                // The manifest identifies the plugin only after bounded staging extraction (Layout B).
+                                const pluginId = indexed.pluginId;
+                                const packagesDir = workspaceLayout.pluginPackagesDir({ pluginId });
+                                await persistentState.assertOwnedPath({ workspaceRoot: workspaceLayout.root, entryPath: path.relative(workspaceLayout.root, packagesDir) });
+                                await mkdir(packagesDir, { recursive: true, mode: 0o700 });
+                                const finalRoot = await assertContainedOnDisk(packagesDir, digest);
+                                for (const directory of [workspaceLayout.pluginDataDir({ pluginId }),
+                                    workspaceLayout.pluginMemoryDir({ pluginId, kind: 'learned' }),
+                                    workspaceLayout.pluginMemoryDir({ pluginId, kind: 'notes' })]) {
+                                    await persistentState.assertOwnedPath({ workspaceRoot: workspaceLayout.root, entryPath: path.relative(workspaceLayout.root, directory) });
+                                    await mkdir(directory, { recursive: true, mode: 0o700 });
+                                }
+                                if (await isRealDirectory(finalRoot)) {
+                                    publishedPlugin = await indexInstalledRoot(finalRoot, digest);
+                                    return publishedPlugin;
+                                }
+                                await publish(extractionRoot, finalRoot);
+                                await freezeTree(finalRoot, executablePaths);
+                                /** Absolute, read-only (frozen) path to the extracted package root. */
+                                publishedPlugin = { ...indexed, packageRoot: finalRoot };
+                                return publishedPlugin;
+                            };
+                            const installed = await (optional.publishGuard ? optional.publishGuard({ plugin: indexed, publish: publishPackage }, {}) : publishPackage());
+                            if (publishedPlugin)
+                                await pruneSupersededRevisions({ workspaceRoot: workspaceLayout.root, installed: publishedPlugin });
+                            return installed;
+                        } });
+                    if (ports.identityAdmission)
+                        return ports.identityAdmission({ id: indexed.id, localId: indexed.pluginId, run: publishWithinPluginLock }, {});
+                    return publishWithinPluginLock();
                 } });
         }
         finally {
@@ -379,6 +452,8 @@ function buildModule(ports) {
             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 })) {
@@ -401,6 +476,8 @@ function buildModule(ports) {
         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

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

@@ -0,0 +1,16 @@
+import type { AgentPluginLifecyclePorts } from './ports.js';
+export declare const INSTALLED_PLUGIN_DIGEST_PATTERN: RegExp;
+export interface InstalledPackageRoot {
+    readonly localId: string;
+    readonly archiveDigest: string;
+    readonly packageRoot: string;
+}
+/** Enumerates contained installed revisions; missing stores are empty. A corrupt slot is
+ * isolated, matching the full installed-plugin index's existing recovery contract.
+ * @complexity O(d) directory/containment operations for d revisions; no executable imports.
+ */
+export declare function listInstalledPackageRoots({ ports, workspaceRoot }: {
+    ports: AgentPluginLifecyclePorts;
+    workspaceRoot: string;
+}, _optional?: Record<string, never>): Promise<readonly InstalledPackageRoot[]>;
+//# sourceMappingURL=installed-package-roots.d.ts.map

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

@@ -0,0 +1,55 @@
+/** The installed-package walk shared by full indexing and identity admission. Reusing this
+ * traversal preserves the same digest grammar, memory-folder exclusion and containment checks. */
+import path from 'node:path';
+import { createPersistentStateModule } from './persistent-state.js';
+import { createPackagePathsModule } from './package-paths.js';
+export const INSTALLED_PLUGIN_DIGEST_PATTERN = /^[a-f0-9]{64}$/;
+/** Enumerates contained installed revisions; missing stores are empty. A corrupt slot is
+ * isolated, matching the full installed-plugin index's existing recovery contract.
+ * @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);
+    let folders;
+    try {
+        folders = await readdir(workspaceRoot, { withFileTypes: true });
+    }
+    catch (error) {
+        if (isEnoent(error))
+            return [];
+        throw error;
+    }
+    const roots = [];
+    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;
+        try {
+            await persistentState.assertOwnedPath({ workspaceRoot, entryPath: path.relative(workspaceRoot, packagesDir) });
+            entries = await readdir(packagesDir, { withFileTypes: true });
+        }
+        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.
+            }
+        }
+    }
+    return roots;
+}
+/** Only a genuinely missing store is empty; other filesystem faults propagate unchanged. */
+function isEnoent(error) {
+    return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+//# sourceMappingURL=installed-package-roots.js.map

package/dist/lifecycle/manifest.d.ts

@@ -1,57 +1,3 @@
-/**
- * @file `parseAgentPluginManifest()` / `parseAgentPluginMcpConfig()` — the Agent Plugins v1.0.0
- * `plugin.json` / `mcp.json` grammar (agent-plugins.org/specification), verified against the live
- * spec rather than inferred from an example manifest.
- *
- * Deliberately a SEPARATE, smaller validator from `src/features/plugin-runtime/manifest.ts`'s
- * `validateManifest()`. That file validates `.host-plugin`'s own tarball format — `integrity`
- * (per-file SHA-256), `sdkRange`, `tier`, an exactly-three-token capability vocabulary, a single
- * `content.entry.beforeSave` hook. This file validates the OPEN standard's `plugin.json`, which
- * 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:
- * - `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`.
- * - 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>": {...} } }` —
- *   `mcpServers` MUST be an object whose member names identify servers.
- * - Each server entry MUST carry a `type` discriminator matching one of three CLOSED variants.
- *   Launching requires the actual transport config, not just a server id:
- *     - `stdio`: requires `command` (non-empty string); optional `args` (string[]), `env`
- *       (string-valued object — MUST NOT set `PLUGIN_ROOT`/`PLUGIN_DATA`, which the spec reserves),
- *       `cwd` (plugin-relative path).
- *     - `streamable-http` / `sse`: requires `url` (non-empty string); optional `headers`
- *       (string-valued object).
- * - **The spec defines NO auth-related field on a server entry at all.** Verbatim from
- *   `/specification`: "Agent Plugins v1 defines no OAuth configuration or portable
- *   credential-reference fields. Authorization discovery, user interaction, and credential storage
- *   are client-managed." A plugin therefore cannot declare "this server needs OAuth" using any
- *   spec-defined field — the host is the client the spec defers that decision to. This module accepts
- *   the host-specific metadata in `plugin.json`'s `extensions.<host-namespace>.mcpServers[serverId]`, keeping
- *   `mcp.json` transport entries closed per §7.2.1. Hosts may translate legacy auth and sign-in defaults in MCP
- *   entries through readServerMetadata for existing packages, but those cannot supply operator read trust.
- *   `authMode: "oauth" | "none"` selects client auth; absent defaults to "none".
- *   `defaultTools: { allow?, write?, read? }` names sign-in grants and reviewed read tools.
- *   `write` requires `allow` and must be its subset; `read` must be a subset when `allow` is
- *   present. A read-only declaration without `allow` leaves sign-in grants unchanged.
- *   Remote hints may veto a read declaration but never supply it. A third,
- *   `tokenAuth: { helpUrl, probeUrl }`, offers a pasted access token as the sign-in fallback
- *   (`access-token-tool.ts`). A fourth, `renamedTools: { oldName: newName }`, carries saved tool
- *   selections across a vendor's tool rename (`apply-tool-renames.ts`). A malformed per-server entry
- *   (wrong/missing `type`, missing required field) does not fail the whole file — see
- *   `ParseAgentPluginMcpConfigResult`'s own doc for the fail-open contract this preserves.
- *
- * Architectural role:
- * Pure, no-I/O parsing over an already-`JSON.parse`d value — mirrors `plugin-runtime/manifest.ts`'s
- * 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.
- */
 export { validatePluginManifest, validateMcpManifest } from '../manifest.js';
 export type { PluginManifest, McpManifest, McpServerEntry } from '../manifest.js';
 import type { PluginManifestAuthor } from '../manifest.js';
@@ -70,6 +16,9 @@ export interface AgentPluginManifest {
     readonly license?: (string) | undefined;
     readonly keywords?: (readonly string[]) | undefined;
     readonly extensions?: (Readonly<Record<string, unknown>>) | undefined;
+    /** Normalized publisher identity, independent of name/storage key and version. */
+    readonly id?: string | undefined;
+    readonly provides?: readonly string[] | undefined;
 }
 export type ParseAgentPluginManifestResult = {
     readonly ok: true;
@@ -89,6 +38,8 @@ export type ParseAgentPluginManifestResult = {
  */
 export declare function parseAgentPluginManifest({ value }: {
     readonly value: unknown;
+}, { identityNamespace }?: {
+    readonly identityNamespace?: string;
 }): ParseAgentPluginManifestResult;
 /**
  * The three closed transport variants `mcp.schema.json` v1.0.0 defines. See this file's header for

package/dist/lifecycle/manifest.js

@@ -52,6 +52,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 { 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
@@ -84,13 +85,6 @@ function isJsonObject(value) {
 function coerceOptionalString(value) {
     return typeof value === "string" ? value : undefined;
 }
-/**
- * `value` narrowed to a `string[]` (non-string entries dropped), or `undefined` when `value`
- * itself isn't an array — `keywords`'s own coercion.
- */
-function coerceStringArray(value) {
-    return Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : undefined;
-}
 function parseManifestAuthor(value) {
     if (typeof value === 'string')
         return value; // Existing installed manifests may carry a string.
@@ -127,7 +121,7 @@ function resolveManifestName(raw) {
  * `plugin-runtime/discovery.ts`).
  * @complexity O(k + n) time and space in the input keys and keyword entries.
  */
-export function parseAgentPluginManifest({ value }) {
+export function parseAgentPluginManifest({ value }, { identityNamespace = "tovu" } = {}) {
     if (!isJsonObject(value))
         return { ok: false, errors: ["plugin.json must be a JSON object"] };
     const raw = value;
@@ -145,15 +139,20 @@ export function parseAgentPluginManifest({ value }) {
         if (!KNOWN_MANIFEST_KEYS.has(key))
             warnings.push(`unrecognized plugin.json field '${key}' (ignored per spec)`);
     }
+    errors.push(...validatePluginIdentity({ manifest: raw, namespace: identityNamespace }).errors);
     if (errors.length > 0)
         return { ok: false, errors };
+    const identity = readPluginIdentity({ manifest: raw, namespace: identityNamespace });
+    warnings.push(...identity.warnings);
     const manifest = {
         name: nameResult.name,
+        id: identity.id,
+        provides: identity.provides,
         version: coerceOptionalString(raw.version),
         description: coerceOptionalString(raw.description),
         author: parseManifestAuthor(raw.author),
         license: coerceOptionalString(raw.license),
-        keywords: coerceStringArray(raw.keywords),
+        keywords: raw.keywords === undefined ? undefined : identity.keywords,
         ...(isJsonObject(raw.extensions) ? { extensions: raw.extensions } : {}),
     };
     return { ok: true, manifest, warnings };

package/dist/lifecycle/persistent-state.d.ts

@@ -1,6 +1,10 @@
 import type { AgentPluginLifecyclePorts } from './ports.js';
 /** Reuses the platform lock with injected effects, never age-stealing a living migration. */
 export declare function createPersistentStateModule(ports: AgentPluginLifecyclePorts, _optional?: Record<string, never>): {
+    withIdentityLock: <T>(required: {
+        workspaceRoot: string;
+        run(): Promise<T>;
+    }, _optional?: {}) => Promise<T>;
     withPluginLock: <T>(required: {
         workspaceRoot: string;
         pluginId: string;

package/dist/lifecycle/persistent-state.js

@@ -1,4 +1,5 @@
 import { createPluginMemory, migratePluginLayout, assertPluginStatePath, withPluginStateLock } from '../../core/persistent-state.js';
+import path from 'node:path';
 import { withFileLock } from '@jini-ai/platform/fs/file-lock';
 import { createPackagePathsModule } from './package-paths.js';
 import { parseAgentPluginManifest } from './manifest.js';
@@ -16,6 +17,7 @@ export function createPersistentStateModule(ports, _optional = {}) {
         }),
     };
     return {
+        withIdentityLock: (required, _optional = {}) => effects.withLock({ lockPath: path.join(required.workspaceRoot, '.publisher-identity.lock'), run: required.run }),
         withPluginLock: (required, optional = {}) => withPluginStateLock({ ...effects, ...required }, optional),
         memory: (required, optional = {}) => createPluginMemory({ ...effects, ...required }, optional),
         assertOwnedPath: (required, optional = {}) => assertPluginStatePath({ ...effects, ...required }, optional),

package/dist/lifecycle/ports.d.ts

@@ -52,6 +52,12 @@ export interface AgentPluginOutboundGuardPort {
     }): Promise<void>;
 }
 export interface AgentPluginLifecyclePorts {
+    /** Optional host admission serializes cross-kind identity checking and publication. */
+    readonly identityAdmission?: (<T>(required: {
+        id: string;
+        localId: string;
+        run: () => Promise<T>;
+    }, optional?: Record<string, never>) => Promise<T>) | undefined;
     readonly onEvent?: ((required: {
         readonly event: string;
         readonly message: string;
@@ -88,6 +94,6 @@ export interface AgentPluginLifecyclePorts {
     readonly outboundGuard: AgentPluginOutboundGuardPort;
 }
 /** Application policy/effects are required; observers and metadata translators are optional. */
-export type AgentPluginLifecycleRequired = Omit<AgentPluginLifecyclePorts, 'onEvent' | 'readServerMetadata' | 'migrateBeforeSeed' | 'formatBundledUninstallRecovery'>;
-export type AgentPluginLifecycleOptional = Pick<AgentPluginLifecyclePorts, 'onEvent' | 'readServerMetadata' | 'migrateBeforeSeed' | 'formatBundledUninstallRecovery'>;
+export type AgentPluginLifecycleRequired = Omit<AgentPluginLifecyclePorts, 'onEvent' | 'readServerMetadata' | 'migrateBeforeSeed' | 'formatBundledUninstallRecovery' | 'identityAdmission'>;
+export type AgentPluginLifecycleOptional = Pick<AgentPluginLifecyclePorts, 'onEvent' | 'readServerMetadata' | 'migrateBeforeSeed' | 'formatBundledUninstallRecovery' | 'identityAdmission'>;
 //# sourceMappingURL=ports.d.ts.map

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

@@ -1,3 +1,4 @@
+import { listInstalledPackageRoots, INSTALLED_PLUGIN_DIGEST_PATTERN } from "./installed-package-roots.js";
 /**
  * @file Resolves a run's pinned Agent Plugin refs (`pluginRefIds` — `run-start-context.ts`'s
  * decoded `contextRef` field, itself sourced from the composer's `pluginRefId` chips,
@@ -65,13 +66,11 @@ import { createCapabilityProjectionModule } from "./capability-projection.js";
 function buildModule(ports) {
     const persistentState = createPersistentStateModule(ports);
     const { assertContainedOnDisk } = createPackagePathsModule(ports);
-    const readdir = ports.filesystem.readdir.bind(ports.filesystem);
     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 SHA256_DIGEST_DIRNAME_PATTERN = /^[a-f0-9]{64}$/;
     /** 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; }
@@ -147,40 +146,15 @@ function buildModule(ports) {
    *  re-walking `packages/sha256/*` a second, less-validated way keeps the digest-directory-name check
    *  and the per-digest failure isolation in exactly one place. */
     async function listInstalledPlugins(workspaceRoot) {
-        let folders;
-        try {
-            folders = await readdir(workspaceRoot, { withFileTypes: true });
-        }
-        catch (error) {
-            if (isEnoent(error))
-                return [];
-            throw error;
-        }
         const installed = [];
-        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;
+        for (const root of await listInstalledPackageRoots({ ports, workspaceRoot })) {
             try {
-                await persistentState.assertOwnedPath({ workspaceRoot, entryPath: path.relative(workspaceRoot, packagesDir) });
-                entries = await readdir(packagesDir, { withFileTypes: true });
+                const plugin = await indexInstalledRoot(root.packageRoot, root.archiveDigest);
+                if (plugin.pluginId === root.localId)
+                    installed.push(plugin);
             }
             catch {
-                continue;
-            }
-            for (const entry of entries) {
-                if (!entry.isDirectory() || !SHA256_DIGEST_DIRNAME_PATTERN.test(entry.name))
-                    continue;
-                try {
-                    const packageRoot = await assertContainedOnDisk(workspaceRoot, path.relative(workspaceRoot, path.join(packagesDir, entry.name)));
-                    const plugin = await indexInstalledRoot(packageRoot, entry.name);
-                    if (plugin.pluginId === folder.name)
-                        installed.push(plugin);
-                }
-                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 installed;
@@ -208,7 +182,7 @@ function buildModule(ports) {
    * @complexity One `stat`.
    */
     async function isInstalledDigestPresent(packagesDir, archiveDigest) {
-        if (!SHA256_DIGEST_DIRNAME_PATTERN.test(archiveDigest))
+        if (!INSTALLED_PLUGIN_DIGEST_PATTERN.test(archiveDigest))
             return false;
         try {
             return (await stat(path.join(packagesDir, archiveDigest))).isDirectory();
@@ -217,9 +191,6 @@ function buildModule(ports) {
             return false;
         }
     }
-    function isEnoent(error) {
-        return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
-    }
     /**
    * Resolves one `pluginRefId`, applying the zero/one/many-match rules described in this module's
    * own header.

package/dist/lifecycle/search.d.ts

@@ -67,6 +67,8 @@ export interface AgentPluginSearchCandidate {
     readonly summary?: string | undefined;
     readonly description?: (string) | undefined;
     readonly keywords: readonly string[];
+    readonly id?: string | undefined;
+    readonly provides?: readonly string[] | undefined;
     /** Whether this workspace currently has the plugin enabled — reflects `activation.ts`'s
      *  absent-means-active default, same as everywhere else this codebase reads activation state. */
     readonly enabled: boolean;

package/dist/lifecycle/search.js

@@ -18,8 +18,8 @@ function buildModule(ports) {
    *  plain, independently-readable list rather than interleaved with the scoring loop itself. */
     function fieldHaystacks(candidate) {
         return [
-            { text: candidate.pluginId.toLowerCase(), weight: ID_FIELD_WEIGHT },
-            { text: candidate.keywords.join(" ").toLowerCase(), weight: KEYWORD_FIELD_WEIGHT },
+            { text: `${candidate.pluginId} ${candidate.id ?? ""}`.toLowerCase(), weight: ID_FIELD_WEIGHT },
+            { text: [...candidate.keywords, ...(candidate.provides ?? [])].join(" ").toLowerCase(), weight: KEYWORD_FIELD_WEIGHT },
             { text: (candidate.description ?? "").toLowerCase(), weight: DESCRIPTION_FIELD_WEIGHT },
             {
                 text: candidate.skills.map((skill) => `${skill.name} ${skill.summary}`).join(" ").toLowerCase(),

package/dist/lifecycle/types.d.ts

@@ -6,6 +6,8 @@ export interface InstalledAgentPluginSkill {
     readonly skillPath: string;
 }
 export interface InstalledAgentPlugin {
+    readonly id?: string | undefined;
+    readonly provides?: readonly string[] | undefined;
     readonly pluginId: string;
     readonly version?: (string) | undefined;
     /** the host extension namespace in `plugin.json`: `displayName` — the human-facing title when the id alone reads

package/dist/manifest.d.ts

@@ -20,6 +20,7 @@ export interface PluginManifestAuthor {
     readonly email?: string;
     readonly url?: string;
 }
+export type { PluginIdentityExtension } from "@jini-ai/core/plugin-directory";
 export interface PluginManifest {
     readonly $schema?: string;
     /** 1-64 chars, lowercase alphanumeric/dots/hyphens, no leading/trailing/doubled separators. */
@@ -60,6 +61,8 @@ export declare function isMcpManifest(value: unknown): value is McpManifest;
 /** Object-argument facade for the legacy structural validator. */
 export declare function validatePluginManifest(required: {
     readonly value: unknown;
+}, optional?: {
+    readonly identityNamespace?: string;
 }): boolean;
 /** Object-argument facade for the legacy structural validator. */
 export declare function validateMcpManifest(required: {

package/dist/manifest.js

@@ -1,3 +1,4 @@
+import { validatePluginIdentity } from "@jini-ai/core/plugin-directory";
 /**
  * Types for the Agent Plugins 1.0.0 open standard (published by a Technical Steering Committee
  * with maintainers from Amazon, Cursor, Google, Microsoft, OpenAI, and Vercel). A plugin is a
@@ -28,8 +29,8 @@ export function isMcpManifest(value) {
     return typeof servers === 'object' && servers !== null && !Array.isArray(servers);
 }
 /** Object-argument facade for the legacy structural validator. */
-export function validatePluginManifest(required) {
-    return isPluginManifest(required.value);
+export function validatePluginManifest(required, optional = {}) {
+    return isPluginManifest(required.value) && validatePluginIdentity({ manifest: required.value, namespace: optional.identityNamespace ?? "tovu" }).errors.length === 0;
 }
 /** Object-argument facade for the legacy structural validator. */
 export function validateMcpManifest(required) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/agent-plugins",
-  "version": "0.4.2",
+  "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.",
   "license": "Apache-2.0",
   "repository": {
@@ -89,21 +89,18 @@
   "devDependencies": {
     "@vitest/coverage-v8": "^2.1.9",
     "yazl": "^3.3.1",
-    "@jini-ai/core": "^0.4.0",
+    "@jini-ai/core": "^0.4.2",
     "@jini-ai/platform": "^0.5.0"
   },
   "peerDependencies": {
     "yauzl": "^3.4.0",
-    "@jini-ai/core": "^0.4.0",
-    "@jini-ai/platform": "^0.5.0"
+    "@jini-ai/core": "^0.4.3",
+    "@jini-ai/platform": "^0.5.3"
   },
   "peerDependenciesMeta": {
     "yauzl": {
       "optional": true
     },
-    "@jini-ai/core": {
-      "optional": true
-    },
     "@jini-ai/platform": {
       "optional": true
     }

package/ui-ux-design/plugin.json

@@ -1,5 +1,19 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "ui-ux-design",
-  "description": "UI/UX design, interface-design-system, accessibility, and shadcn/ui component skills bundled as one portable Agent Plugin."
+  "description": "UI/UX design, interface-design-system, accessibility, and shadcn/ui component skills bundled as one portable Agent Plugin.",
+  "extensions": {
+    "tovu": {
+      "id": "jini/ui-ux-design",
+      "provides": [
+        "ui-design"
+      ]
+    }
+  },
+  "keywords": [
+    "design",
+    "ui",
+    "ux",
+    "ui-design"
+  ]
 }