@abot-ai/runtime 1.6.0 → 1.8.0

package/dist/src/runtime/plugins/installation/installed-package.d.ts

@@ -0,0 +1,9 @@
+import type { DiscoveredAgentPluginManifest } from "../discovered-manifest.js";
+/** Stable package identity also works after moving it outside the discovery directory. */
+export declare function installedPluginPackageIdentity(path: string): string | undefined;
+/** Only installer-owned, direct consumer folders are removable. Never follow links. */
+export declare function installedPluginPackage(rootDir: string, plugin: DiscoveredAgentPluginManifest): {
+    path: string;
+    identity: string;
+    packageIdentity: string;
+} | undefined;

package/dist/src/runtime/plugins/installation/installed-package.js

@@ -0,0 +1,66 @@
+import { lstatSync, readFileSync, realpathSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { parsePluginInstallSource } from "../../../plugin-contract/install-source.js";
+import { isPortablePluginPathComponent } from "./portable-path.js";
+/** Stable package identity also works after moving it outside the discovery directory. */
+export function installedPluginPackageIdentity(path) {
+    try {
+        const folder = lstatSync(path);
+        const receiptPath = join(path, ".abot-install.json");
+        const receiptStat = lstatSync(receiptPath);
+        if (!folder.isDirectory() ||
+            !receiptStat.isFile() ||
+            receiptStat.size > 4096)
+            return undefined;
+        const receipt = JSON.parse(readFileSync(receiptPath, "utf8"));
+        if (receipt.schemaVersion !== 1 ||
+            typeof receipt.digest !== "string" ||
+            !/^[a-f0-9]{64}$/u.test(receipt.digest) ||
+            typeof receipt.installedAt !== "string" ||
+            !Number.isFinite(Date.parse(receipt.installedAt)))
+            return undefined;
+        const source = parsePluginInstallSource(receipt.source);
+        if (!source.ref || !/^[a-f0-9]{40}$/u.test(source.ref))
+            return undefined;
+        const manifestPath = join(path, "plugin.json");
+        const manifestStat = lstatSync(manifestPath);
+        if (!manifestStat.isFile())
+            return undefined;
+        return JSON.stringify([
+            folder.dev,
+            folder.ino,
+            folder.birthtimeMs,
+            receipt,
+            readFileSync(manifestPath, "utf8"),
+        ]);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Only installer-owned, direct consumer folders are removable. Never follow links. */
+export function installedPluginPackage(rootDir, plugin) {
+    const id = plugin.manifest.name;
+    if (!isPortablePluginPathComponent(id))
+        return undefined;
+    try {
+        const directory = join(realpathSync(rootDir), "plugins");
+        const path = join(directory, id);
+        if (resolve(plugin.pluginRoot) !== path)
+            return undefined;
+        const parent = lstatSync(directory);
+        if (!parent.isDirectory())
+            return undefined;
+        const packageIdentity = installedPluginPackageIdentity(path);
+        if (!packageIdentity)
+            return undefined;
+        return {
+            path,
+            packageIdentity,
+            identity: JSON.stringify([parent.dev, parent.ino, packageIdentity]),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/src/runtime/plugins/installation/package.d.ts

@@ -0,0 +1,53 @@
+import { type PluginInstallSource } from "../../../plugin-contract/install-source.js";
+import { ABOT_RUNTIME_EXTENSION } from "../../../plugin-contract/manifest.js";
+import { type PluginSourceFetcher } from "./github-download.js";
+export declare function preparePluginPackage(rootDir: string, source: PluginInstallSource, download?: PluginSourceFetcher): Promise<{
+    staging: string;
+    manifest: Readonly<{
+        $schema: typeof import("../../../plugin-contract/manifest.js").AGENT_PLUGIN_MANIFEST_SCHEMA;
+        name: string;
+        version?: string;
+        description?: string;
+        extensions: Readonly<{
+            [ABOT_RUNTIME_EXTENSION]: import("../../../plugin-contract/manifest.js").AbotRuntimePluginExtension;
+            ["ai.abot.compatibility"]?: import("../../../plugin-contract/platform-compatibility.js").PluginPlatformDeclaration;
+            [namespace: string]: unknown;
+        }>;
+    }>;
+    review: {
+        source: Readonly<{
+            repository: string;
+            ref?: string;
+            path?: string;
+        }> & {
+            ref: string;
+        };
+        digest: string;
+        id: string;
+        compatibility: Readonly<{
+            supported: boolean;
+            status: "declared" | "legacy" | "unsupported" | "undeclared";
+            runtimePlatform: NodeJS.Platform;
+            runtimePlatforms?: readonly import("../../../plugin-contract/platform-compatibility.js").PluginRuntimePlatform[];
+            reason?: string;
+        }>;
+        version: string;
+        description: string;
+        capabilities: {
+            id: string;
+            description: string;
+            operations: {
+                name: string;
+                effect: import("../../../capabilities/tool-types.js").ToolNormalInvocationEffect;
+                approval: import("../../../capabilities/tool-types.js").ToolNormalInvocationApproval;
+            }[];
+        }[];
+        settings: Readonly<Record<string, unknown>>;
+        secrets: {
+            name: string;
+            env: string;
+            required: boolean;
+        }[];
+    };
+}>;
+export declare function requireNewPluginIdentity(rootDir: string, id: string, capabilityIds: readonly string[]): void;

package/dist/src/runtime/plugins/installation/package.js

@@ -0,0 +1,81 @@
+import { mkdtemp, readFile, readdir, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { PluginInstallError, } from "../../../plugin-contract/install-source.js";
+import { ABOT_RUNTIME_EXTENSION } from "../../../plugin-contract/manifest.js";
+import { resolvePluginPlatformCompatibility } from "../platform-compatibility.js";
+import { parseAgentPluginManifest } from "../manifest-validator.js";
+import { projectManifestRuntimeContract } from "../manifest-projection.js";
+import { discoverConfiguredRuntimePluginManifests } from "../configured-manifests.js";
+import { extractPluginArchive } from "./archive.js";
+import { isPortablePluginPathComponent } from "./portable-path.js";
+import { downloadGitHubPlugin, } from "./github-download.js";
+async function requireAvailableInstallMetadataPath(staging) {
+    const names = await readdir(staging);
+    if (names.some((name) => name.toLowerCase() === ".abot-install.json"))
+        throw new PluginInstallError("plugin_package_invalid", "The selected plugin contains the reserved .abot-install.json path.");
+}
+export async function preparePluginPackage(rootDir, source, download = downloadGitHubPlugin) {
+    const downloaded = await download(source);
+    if (!/^[a-f0-9]{40}$/u.test(downloaded.source.ref))
+        throw new PluginInstallError("plugin_revision_invalid", "The source must resolve to an exact commit.");
+    const staging = await mkdtemp(join(rootDir, ".abot-plugin-install-"));
+    try {
+        const digest = await extractPluginArchive(downloaded.archive, staging, downloaded.source.path);
+        await requireAvailableInstallMetadataPath(staging);
+        const raw = JSON.parse(await readFile(join(staging, "plugin.json"), "utf8"));
+        const manifest = parseAgentPluginManifest(raw, typeof raw.name === "string" ? raw.name : "");
+        if (!isPortablePluginPathComponent(manifest.name))
+            throw new PluginInstallError("plugin_package_invalid", "The plugin ID cannot be used as a portable installation folder name.");
+        const extension = manifest.extensions[ABOT_RUNTIME_EXTENSION];
+        if (!extension.entrypoint.endsWith(".cjs"))
+            throw new PluginInstallError("plugin_package_not_built", "This plugin must include a ready-to-run CommonJS .cjs entrypoint.");
+        const capabilities = Object.keys(extension.capabilities);
+        projectManifestRuntimeContract({
+            pluginRoot: staging,
+            manifestPath: join(staging, "plugin.json"),
+            manifest,
+        }, capabilities);
+        requireNewPluginIdentity(rootDir, manifest.name, capabilities);
+        return {
+            staging,
+            manifest,
+            review: {
+                source: downloaded.source,
+                digest,
+                id: manifest.name,
+                compatibility: resolvePluginPlatformCompatibility(manifest),
+                version: manifest.version ?? "",
+                description: manifest.description ?? "",
+                capabilities: capabilities.map((id) => ({
+                    id,
+                    description: extension.capabilities[id].description,
+                    operations: Object.entries(extension.capabilities[id].operations).map(([name, operation]) => ({
+                        name,
+                        effect: operation.effect,
+                        approval: operation.approval,
+                    })),
+                })),
+                settings: extension.settings?.defaults ?? {},
+                secrets: Object.entries(extension.secrets ?? {}).map(([name, secret]) => ({
+                    name,
+                    env: secret.env,
+                    required: secret.required,
+                })),
+            },
+        };
+    }
+    catch (error) {
+        await rm(staging, { recursive: true, force: true });
+        if (error instanceof PluginInstallError)
+            throw error;
+        throw new PluginInstallError("plugin_package_invalid", "The selected folder is not a complete, valid ABot plugin. Check plugin.json, its built entrypoint and referenced skills.");
+    }
+}
+export function requireNewPluginIdentity(rootDir, id, capabilityIds) {
+    const installed = discoverConfiguredRuntimePluginManifests(rootDir);
+    if (installed.some((plugin) => plugin.manifest.name === id))
+        throw new PluginInstallError("plugin_already_installed", "A plugin with this ID is already installed. Existing plugins are never replaced.", 409);
+    const existing = new Set(installed.flatMap((plugin) => Object.keys(plugin.manifest.extensions[ABOT_RUNTIME_EXTENSION].capabilities)));
+    if (capabilityIds.some((capability) => existing.has(capability)))
+        throw new PluginInstallError("plugin_capability_conflict", "This plugin declares a capability ID already provided by another installed plugin.", 409);
+}

package/dist/src/runtime/plugins/installation/portable-path.d.ts

@@ -0,0 +1,2 @@
+/** Files and manifest-derived installation folders share the same portable naming rules. */
+export declare function isPortablePluginPathComponent(name: string): boolean;

package/dist/src/runtime/plugins/installation/portable-path.js

@@ -0,0 +1,10 @@
+/** Files and manifest-derived installation folders share the same portable naming rules. */
+export function isPortablePluginPathComponent(name) {
+    if (!name || name === "." || name === "..")
+        return false;
+    if (/[<>:"/\\|?*\u0000-\u001f\u007f]/u.test(name))
+        return false;
+    if (/[. ]$/u.test(name))
+        return false;
+    return !/^(con|prn|aux|nul|com[1-9\u00b9\u00b2\u00b3]|lpt[1-9\u00b9\u00b2\u00b3])(?:\.|$)/iu.test(name);
+}

package/dist/src/runtime/plugins/installation/publication.d.ts

@@ -0,0 +1,10 @@
+import { type ConfigFileTransaction } from "../../adapters/config-file-transaction.js";
+/** Publish, save selection and roll back under the same lock used by Apply. */
+export declare function publishPluginPackage<T>(options: {
+    staging: string;
+    target: string;
+    pluginId: string;
+    configPath: string;
+    requireMutationIdle?: () => void;
+    saveSelection: (pluginId: string, transaction: ConfigFileTransaction) => Promise<T>;
+}): Promise<T>;

package/dist/src/runtime/plugins/installation/publication.js

@@ -0,0 +1,17 @@
+import { rename, rm } from "node:fs/promises";
+import { withConfigFileTransaction, } from "../../adapters/config-file-transaction.js";
+/** Publish, save selection and roll back under the same lock used by Apply. */
+export function publishPluginPackage(options) {
+    return withConfigFileTransaction(options.configPath, async (transaction) => {
+        options.requireMutationIdle?.();
+        await rename(options.staging, options.target);
+        try {
+            return await options.saveSelection(options.pluginId, transaction);
+        }
+        catch (error) {
+            // Apply cannot load the uncommitted package while rollback is in progress.
+            await rm(options.target, { recursive: true, force: true });
+            throw error;
+        }
+    });
+}

package/dist/src/runtime/plugins/installation/service.d.ts

@@ -0,0 +1,48 @@
+import type { ConfigFileTransaction } from "../../adapters/config-file-transaction.js";
+import type { PluginSourceFetcher } from "./github-download.js";
+export declare function inspectPluginPackage(rootDir: string, input: unknown, download?: PluginSourceFetcher): Promise<{
+    source: Readonly<{
+        repository: string;
+        ref?: string;
+        path?: string;
+    }> & {
+        ref: string;
+    };
+    digest: string;
+    id: string;
+    compatibility: Readonly<{
+        supported: boolean;
+        status: "declared" | "legacy" | "unsupported" | "undeclared";
+        runtimePlatform: NodeJS.Platform;
+        runtimePlatforms?: readonly import("../../../plugin-contract/platform-compatibility.js").PluginRuntimePlatform[];
+        reason?: string;
+    }>;
+    version: string;
+    description: string;
+    capabilities: {
+        id: string;
+        description: string;
+        operations: {
+            name: string;
+            effect: import("../../../capabilities/tool-types.js").ToolNormalInvocationEffect;
+            approval: import("../../../capabilities/tool-types.js").ToolNormalInvocationApproval;
+        }[];
+    }[];
+    settings: Readonly<Record<string, unknown>>;
+    secrets: {
+        name: string;
+        env: string;
+        required: boolean;
+    }[];
+}>;
+export declare function installPluginPackage<T>(options: {
+    rootDir: string;
+    input: unknown;
+    download?: PluginSourceFetcher;
+    configPath?: string;
+    saveSelection: (pluginId: string, transaction: ConfigFileTransaction) => Promise<T>;
+    requireMutationIdle?: () => void;
+}): Promise<{
+    installed: Awaited<ReturnType<typeof inspectPluginPackage>>;
+    snapshot: T;
+}>;

package/dist/src/runtime/plugins/installation/service.js

@@ -0,0 +1,80 @@
+import { lstat, mkdir, realpath, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { PluginInstallError, parsePluginInstallSource, } from "../../../plugin-contract/install-source.js";
+import { inspectRuntimeConfigFileWithMeta } from "../../config/loader.js";
+import { publishPluginPackage } from "./publication.js";
+import { withFileLock } from "../../adapters/long-term-memory/file-lock.js";
+import { preparePluginPackage, requireNewPluginIdentity } from "./package.js";
+function isAbsentPath(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+async function installationDirectory(rootDir) {
+    const path = join(rootDir, "plugins");
+    await mkdir(path, { mode: 0o700 }).catch((error) => {
+        if (error.code !== "EEXIST")
+            throw error;
+    });
+    const stat = await lstat(path);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new PluginInstallError("plugin_destination_invalid", "The plugins destination must be a local directory.");
+    return path;
+}
+export async function inspectPluginPackage(rootDir, input, download) {
+    const root = await realpath(rootDir);
+    const prepared = await preparePluginPackage(root, parsePluginInstallSource(input), download);
+    try {
+        return prepared.review;
+    }
+    finally {
+        await rm(prepared.staging, { recursive: true, force: true });
+    }
+}
+export async function installPluginPackage(options) {
+    const input = options.input;
+    if (!input ||
+        typeof input !== "object" ||
+        typeof input.digest !== "string" ||
+        !/^[a-f0-9]{64}$/u.test(input.digest))
+        throw new PluginInstallError("plugin_review_required", "Review the plugin before installing it.");
+    const source = parsePluginInstallSource(input.source);
+    if (!source.ref || !/^[a-f0-9]{40}$/u.test(source.ref))
+        throw new PluginInstallError("plugin_review_required", "Installation requires the exact reviewed commit.");
+    const root = await realpath(options.rootDir);
+    const prepared = await preparePluginPackage(root, source, options.download);
+    try {
+        if (prepared.review.digest !== input.digest ||
+            prepared.review.source.ref !== source.ref)
+            throw new PluginInstallError("plugin_review_changed", "The plugin changed since review. Inspect it again.", 409);
+        return await withFileLock(join(root, ".abot-plugin-installation"), async () => {
+            const directory = await installationDirectory(root);
+            requireNewPluginIdentity(root, prepared.manifest.name, prepared.review.capabilities.map((capability) => capability.id));
+            const target = join(directory, prepared.manifest.name);
+            const existing = await lstat(target).catch((error) => {
+                if (isAbsentPath(error))
+                    return undefined;
+                throw error;
+            });
+            if (existing)
+                throw new PluginInstallError("plugin_already_installed", "The destination already exists; it will not be overwritten.", 409);
+            await writeFile(join(prepared.staging, ".abot-install.json"), JSON.stringify({
+                schemaVersion: 1,
+                source: prepared.review.source,
+                digest: prepared.review.digest,
+                installedAt: new Date().toISOString(),
+            }) + "\n", { flag: "wx", mode: 0o600 });
+            const snapshot = await publishPluginPackage({
+                staging: prepared.staging,
+                target,
+                pluginId: prepared.manifest.name,
+                configPath: inspectRuntimeConfigFileWithMeta(root, options.configPath)
+                    .path,
+                requireMutationIdle: options.requireMutationIdle,
+                saveSelection: options.saveSelection,
+            });
+            return { installed: prepared.review, snapshot };
+        });
+    }
+    finally {
+        await rm(prepared.staging, { recursive: true, force: true });
+    }
+}

package/dist/src/runtime/plugins/loader.js

@@ -1,3 +1,5 @@
+import { pluginLoadConfiguration } from "./configuration-context.js";
+import { readPluginConfigurationStore, } from "./configuration-store.js";
 import { validateManifestEntrypoint } from "./entrypoint-validation.js";
 import { createRequire } from "node:module";
 import { join } from "node:path";
@@ -9,6 +11,7 @@ import { discoverAgentPluginManifests } from "./manifest-discovery.js";
 import { resolveBundledRuntimeRoot } from "./bundled-root.js";
 import { projectManifestRuntimeContract } from "./manifest-projection.js";
 import { discoverConfiguredRuntimePluginManifests } from "./configured-manifests.js";
+import { resolvePluginPlatformCompatibility } from "./platform-compatibility.js";
 import { isPluginCatalogDisabled, isPluginToolSelected, normalizePluginSelection, pluginSelectionCacheKey, } from "./selection.js";
 const require = createRequire(import.meta.url);
 const compiledCatalogCache = new WeakMap();
@@ -16,9 +19,6 @@ const bundledCatalogCache = new Map();
 function isRecord(value) {
     return !!value && typeof value === "object" && !Array.isArray(value);
 }
-function nonEmptyString(value) {
-    return typeof value === "string" && value.trim().length > 0;
-}
 function unwrapPluginExport(rawModule) {
     if (isRecord(rawModule) &&
         "default" in rawModule &&
@@ -36,32 +36,14 @@ function compiledCapabilityFromDeclaration(tool) {
         normalInvocation: tool.normalInvocation,
     };
 }
-function createManifestSecretAccessor(pluginId, declarations) {
-    if (!declarations || Object.keys(declarations).length === 0) {
-        return undefined;
-    }
-    for (const [name, declaration] of Object.entries(declarations)) {
-        if (declaration.required && !nonEmptyString(process.env[declaration.env])) {
-            throw new Error(`Runtime plugin ${pluginId} requires secret ${name} from environment variable ${declaration.env}`);
-        }
-    }
-    return Object.freeze({
-        get(name) {
-            const declaration = declarations[name];
-            if (!declaration) {
-                throw new Error(`Runtime plugin ${pluginId} requested undeclared secret ${name}`);
-            }
-            const value = process.env[declaration.env];
-            return nonEmptyString(value) ? value : undefined;
-        },
-    });
-}
 function loadManifestRuntimePlugin(host, discovered, selectedCapabilityIds) {
     const manifest = discovered.manifest;
     const extension = manifest.extensions[ABOT_RUNTIME_EXTENSION];
     const capabilityIds = Object.keys(extension.capabilities);
     const projection = projectManifestRuntimeContract(discovered, selectedCapabilityIds);
-    const secrets = createManifestSecretAccessor(manifest.name, extension.secrets);
+    const configuration = pluginLoadConfiguration(manifest.name, extension, Object.hasOwn(host.pluginConfiguration, manifest.name)
+        ? host.pluginConfiguration[manifest.name]
+        : undefined);
     let loaded;
     try {
         loaded = unwrapPluginExport(require(projection.entryPath));
@@ -80,10 +62,7 @@ function loadManifestRuntimePlugin(host, discovered, selectedCapabilityIds) {
         runtimePaths: host.runtimePaths,
         runtimePathResolver: createRuntimeToolPathResolver(host.runtimePaths),
         pluginRoot: discovered.pluginRoot,
-        ...(extension.settings
-            ? { config: { ...extension.settings.defaults } }
-            : {}),
-        ...(secrets ? { secrets } : {}),
+        ...configuration,
     };
     const rawEntrypoint = typeof loaded === "function"
         ? loaded(loadContext)
@@ -132,13 +111,15 @@ export function loadConfiguredRuntimePlugins(config) {
     if (cached) {
         return cached;
     }
-    const host = {
-        rootDir: config.paths.rootDir,
-        runtimeId: config.runtimeId,
-        agentBridgeUrl: config.agentBridgeUrl,
-        runtimePaths: config.paths,
-    };
-    const manifestPlugins = discoverConfiguredRuntimePluginManifests(config.paths.rootDir, { excludedPluginIds: new Set(selection.deny) })
+    const discoveredPlugins = discoverConfiguredRuntimePluginManifests(config.paths.rootDir, {
+        excludedPluginIds: new Set([
+            ...selection.deny,
+            ...selection.disabledPluginIds,
+        ]),
+    });
+    const compatiblePlugins = discoveredPlugins.filter((plugin) => resolvePluginPlatformCompatibility(plugin.manifest).supported);
+    const allPluginsIncompatible = discoveredPlugins.length > 0 && compatiblePlugins.length === 0;
+    const selectedPlugins = compatiblePlugins
         .map((plugin) => ({
         plugin,
         selectedCapabilityIds: Object.keys(plugin.manifest.extensions[ABOT_RUNTIME_EXTENSION].capabilities).filter((capabilityId) => isPluginToolSelected({
@@ -147,8 +128,17 @@ export function loadConfiguredRuntimePlugins(config) {
             selection,
         })),
     }))
-        .filter(({ selectedCapabilityIds }) => selectedCapabilityIds.length > 0)
-        .map(({ plugin, selectedCapabilityIds }) => loadManifestRuntimePlugin(host, plugin, selectedCapabilityIds));
+        .filter(({ selectedCapabilityIds }) => selectedCapabilityIds.length > 0);
+    const host = {
+        rootDir: config.paths.rootDir,
+        pluginConfiguration: allPluginsIncompatible
+            ? {}
+            : readPluginConfigurationStore(config.paths.rootDir).plugins,
+        runtimeId: config.runtimeId,
+        agentBridgeUrl: config.agentBridgeUrl,
+        runtimePaths: config.paths,
+    };
+    const manifestPlugins = selectedPlugins.map(({ plugin, selectedCapabilityIds }) => loadManifestRuntimePlugin(host, plugin, selectedCapabilityIds));
     const pluginIds = new Set();
     for (const plugin of manifestPlugins) {
         if (pluginIds.has(plugin.id)) {
@@ -190,13 +180,19 @@ export function loadBundledRuntimePlugins() {
     if (cached) {
         return cached;
     }
+    const discoveredPlugins = discoverAgentPluginManifests(packageRoot);
+    const selectedPlugins = discoveredPlugins.filter((plugin) => resolvePluginPlatformCompatibility(plugin.manifest).supported);
+    const allPluginsIncompatible = discoveredPlugins.length > 0 && selectedPlugins.length === 0;
     const host = {
         rootDir,
+        pluginConfiguration: allPluginsIncompatible
+            ? {}
+            : readPluginConfigurationStore(rootDir).plugins,
         runtimeId: "default",
         agentBridgeUrl: "",
         runtimePaths: createUnconfiguredRuntimePaths(rootDir),
     };
-    const catalog = Object.freeze(discoverAgentPluginManifests(packageRoot).map((plugin) => freezeRuntimePlugin(loadManifestRuntimePlugin(host, plugin, Object.keys(plugin.manifest.extensions[ABOT_RUNTIME_EXTENSION].capabilities)))));
+    const catalog = Object.freeze(selectedPlugins.map((plugin) => freezeRuntimePlugin(loadManifestRuntimePlugin(host, plugin, Object.keys(plugin.manifest.extensions[ABOT_RUNTIME_EXTENSION].capabilities)))));
     bundledCatalogCache.set(cacheKey, catalog);
     return catalog;
 }

package/dist/src/runtime/plugins/manifest-platform-compatibility.d.ts

@@ -0,0 +1,2 @@
+import { type PluginPlatformDeclaration } from "../../plugin-contract/platform-compatibility.js";
+export declare function parsePluginPlatformDeclaration(value: unknown): PluginPlatformDeclaration | undefined;

package/dist/src/runtime/plugins/manifest-platform-compatibility.js

@@ -0,0 +1,39 @@
+import { ABOT_PLUGIN_COMPATIBILITY_EXTENSION, ABOT_PLUGIN_COMPATIBILITY_VERSION, PLUGIN_RUNTIME_PLATFORMS, } from "../../plugin-contract/platform-compatibility.js";
+import { isRecord } from "../config/utils.js";
+function hasUnknownCompatibilityField(value) {
+    return Object.keys(value).some((key) => key !== "version" && key !== "runtimePlatforms");
+}
+function isRuntimePlatformList(value) {
+    if (!Array.isArray(value))
+        return false;
+    if (value.length === 0)
+        return false;
+    return value.length <= PLUGIN_RUNTIME_PLATFORMS.length;
+}
+function isPluginRuntimePlatform(value) {
+    return PLUGIN_RUNTIME_PLATFORMS.some((platform) => platform === value);
+}
+function hasRepeatedRuntimePlatform(platforms) {
+    return new Set(platforms).size !== platforms.length;
+}
+export function parsePluginPlatformDeclaration(value) {
+    if (value === undefined)
+        return undefined;
+    const path = `extensions.${ABOT_PLUGIN_COMPATIBILITY_EXTENSION}`;
+    if (!isRecord(value))
+        throw new Error(`${path} must be an object`);
+    if (hasUnknownCompatibilityField(value))
+        throw new Error(`${path} contains an unknown field`);
+    if (value.version !== ABOT_PLUGIN_COMPATIBILITY_VERSION)
+        throw new Error(`${path}.version must be ${ABOT_PLUGIN_COMPATIBILITY_VERSION}`);
+    if (!isRuntimePlatformList(value.runtimePlatforms))
+        throw new Error(`${path}.runtimePlatforms must contain one to three platforms`);
+    if (!value.runtimePlatforms.every(isPluginRuntimePlatform))
+        throw new Error(`${path}.runtimePlatforms must use linux, darwin, or win32`);
+    if (hasRepeatedRuntimePlatform(value.runtimePlatforms))
+        throw new Error(`${path}.runtimePlatforms must not contain duplicates`);
+    return Object.freeze({
+        version: ABOT_PLUGIN_COMPATIBILITY_VERSION,
+        runtimePlatforms: Object.freeze([...value.runtimePlatforms]),
+    });
+}

package/dist/src/runtime/plugins/manifest-projection.js

@@ -71,6 +71,7 @@ export function projectManifestRuntimeContract(discovered, selectedCapabilityIds
                 operations: Object.entries(capability.operations).map(([operationId, operation]) => ({
                     operationId,
                     summary: operation.summary,
+                    ...(operation.outputChannels ? { outputChannels: operation.outputChannels } : {}),
                     input: operation.input,
                     ...(operation.selectionControlIds
                         ? { selectionControlIds: operation.selectionControlIds }

package/dist/src/runtime/plugins/manifest-validator.js

@@ -1,4 +1,7 @@
+import { parseOptionalToolOutputChannels } from "../../capabilities/normal-invocation/output-channels.js";
 import { parseRequiredToolPermissionMode } from "../../capabilities/tool-permission-mode.js";
+import { ABOT_PLUGIN_COMPATIBILITY_EXTENSION } from "../../plugin-contract/platform-compatibility.js";
+import { parsePluginPlatformDeclaration } from "./manifest-platform-compatibility.js";
 import { isToolCatalogGroupId } from "../../capabilities/tool-types.js";
 import { parseEventResultMetadata } from "../../capabilities/tool-definition-validator/event-result-metadata.js";
 import { parseEventInputTextOptions } from "../../capabilities/tool-definition-validator/event-input-text-options.js";
@@ -276,6 +279,7 @@ function parseOperation(value, path) {
     const operation = expectRecord(value, path);
     rejectUnknownKeys(operation, [
         "summary",
+        "outputChannels",
         "input",
         "selectionControlIds",
         "effect",
@@ -309,6 +313,7 @@ function parseOperation(value, path) {
     return {
         manifest: {
             summary: operation.summary.trim(),
+            ...parseOptionalToolOutputChannels(operation.outputChannels, `${path}.outputChannels`),
             input: input,
             ...(selectionControlIds ? { selectionControlIds } : {}),
             effect: operation.effect,
@@ -318,7 +323,9 @@ function parseOperation(value, path) {
                 ? { payload: payload }
                 : {}),
             ...(attachmentInput
-                ? { attachmentInput: attachmentInput }
+                ? {
+                    attachmentInput: attachmentInput,
+                }
                 : {}),
         },
         ...(legacySkills ? { legacySkills } : {}),
@@ -478,6 +485,7 @@ export function parseAgentPluginManifest(raw, folderName) {
     }
     const extensions = expectRecord(manifest.extensions, "plugin.json.extensions");
     const runtimeExtension = parseRuntimeExtension(extensions[ABOT_RUNTIME_EXTENSION]);
+    const compatibility = parsePluginPlatformDeclaration(extensions[ABOT_PLUGIN_COMPATIBILITY_EXTENSION]);
     return {
         $schema: AGENT_PLUGIN_MANIFEST_SCHEMA,
         name: manifest.name,
@@ -490,6 +498,9 @@ export function parseAgentPluginManifest(raw, folderName) {
         extensions: {
             ...extensions,
             [ABOT_RUNTIME_EXTENSION]: runtimeExtension,
+            ...(compatibility
+                ? { [ABOT_PLUGIN_COMPATIBILITY_EXTENSION]: compatibility }
+                : {}),
         },
     };
 }

package/dist/src/runtime/plugins/module-cache.d.ts

@@ -0,0 +1,2 @@
+/** Retire only this installation's CommonJS graph, including package-local helpers. */
+export declare function evictPluginModules(pluginRoot: string): void;

package/dist/src/runtime/plugins/module-cache.js

@@ -0,0 +1,19 @@
+import { createRequire } from "node:module";
+import { isAbsolute, relative, sep } from "node:path";
+const require = createRequire(import.meta.url);
+/** Retire only this installation's CommonJS graph, including package-local helpers. */
+export function evictPluginModules(pluginRoot) {
+    const removed = new Set();
+    for (const [path, module] of Object.entries(require.cache)) {
+        const child = relative(pluginRoot, path);
+        const outside = isAbsolute(child) || child === ".." || child.startsWith(`..${sep}`);
+        if (outside || !module)
+            continue;
+        removed.add(module);
+        delete require.cache[path];
+    }
+    for (const module of Object.values(require.cache)) {
+        if (module)
+            module.children = module.children.filter((child) => !removed.has(child));
+    }
+}

package/dist/src/runtime/plugins/platform-compatibility.d.ts

@@ -0,0 +1,4 @@
+import type { AgentPluginManifest } from "../../plugin-contract/manifest.js";
+import { type PluginPlatformCompatibility } from "../../plugin-contract/platform-compatibility.js";
+/** Compatibility affects loading, never the user's saved plugin selection. */
+export declare function resolvePluginPlatformCompatibility(manifest: AgentPluginManifest, runtimePlatform?: NodeJS.Platform): PluginPlatformCompatibility;