@abot-ai/runtime 1.3.1 → 1.5.0

package/dist/src/runtime/passive-learning/store.js

@@ -0,0 +1,155 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, writeFile, rename, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { normalizeAnalysisSchedule } from "./analysis-schedule.js";
+import { learningBatchExpiresAt } from "./batch-lifecycle.js";
+import { DEFAULT_MATURATION_POLICY, normalizeMaturationPolicy } from "../long-term-memory/maturation/retention.js";
+import { DEFAULT_CO_WORKER_RESOURCE_LIMITS, validateCoWorkerResourceLimits } from "./resources/contracts.js";
+import { normalizeIndependentLearningPreferences } from "./independent-preferences.js";
+import { normalizeLearningApplications } from "./application-policy.js";
+import { DEFAULT_ANALYSIS_TRIGGER, DEFAULT_ANALYSIS_OBSERVATION_COUNT } from "./processing-trigger.js";
+import { readObservationReviewPass } from "./processing-pass.js";
+import { readCoWorkerReviewProgress } from "./review-progress.js";
+import { normalizeLearningActivityControls } from "./activity-permissions.js";
+export const DEFAULT_LEARNING_PREFERENCES = Object.freeze({
+    enabled: false,
+    processingPaused: true,
+    excludedApplications: Object.freeze([]),
+    processingExcludedApplications: Object.freeze([]),
+    analysisIntervalMinutes: 15,
+    analysisTrigger: DEFAULT_ANALYSIS_TRIGGER,
+    analysisObservationCount: DEFAULT_ANALYSIS_OBSERVATION_COUNT,
+    analysisWindow: null,
+    collectionWindow: null,
+    proactiveEnabled: false,
+    proactiveIntervalMinutes: 60,
+    proactiveWindow: null,
+    proactiveMessagesPerDay: 2,
+    maxConcurrentBatches: 1,
+    maturation: DEFAULT_MATURATION_POLICY,
+    resourceLimits: DEFAULT_CO_WORKER_RESOURCE_LIMITS,
+});
+const HISTORY_MAX_BYTES = 4 * 1024 * 1024;
+export function createLearningStateStore(directory) {
+    const file = join(directory, "state.json");
+    return {
+        async read() {
+            try {
+                const value = JSON.parse(await readFile(file, "utf8"));
+                return parseState(value);
+            }
+            catch (error) {
+                if (isMissing(error))
+                    return {
+                        schemaVersion: 1,
+                        preferences: DEFAULT_LEARNING_PREFERENCES,
+                        batches: [],
+                    };
+                throw error;
+            }
+        },
+        async write(state) {
+            await mkdir(directory, { recursive: true, mode: 0o700 });
+            const temporary = `${file}.${randomUUID()}.tmp`;
+            try {
+                await writeFile(temporary, JSON.stringify(state), {
+                    flag: "wx",
+                    mode: 0o600,
+                });
+                await rename(temporary, file);
+            }
+            finally {
+                await rm(temporary, { force: true });
+            }
+        },
+    };
+}
+export function pruneLearningBatches(batches, now) {
+    const candidates = batches
+        .filter((batch) => now < learningBatchExpiresAt(batch))
+        .slice(-50);
+    let size = candidates.reduce((total, item) => total + Buffer.byteLength(JSON.stringify(item)), 0);
+    while (size > HISTORY_MAX_BYTES && candidates.length)
+        size -= Buffer.byteLength(JSON.stringify(candidates.shift()));
+    return candidates;
+}
+export function normalizeLearningPreferences(input, previous) {
+    if (input.enabled !== undefined && typeof input.enabled !== "boolean")
+        throw new Error("invalid_learning_preferences");
+    if (input.processingPaused !== undefined &&
+        typeof input.processingPaused !== "boolean")
+        throw new Error("invalid_learning_preferences");
+    const profile = input.modelProfileId ?? previous.modelProfileId;
+    if (profile !== undefined &&
+        (typeof profile !== "string" || !profile.trim() || profile.length > 128))
+        throw new Error("invalid_learning_model_profile");
+    const excluded = normalizeLearningApplications(input.excludedApplications ?? previous.excludedApplications);
+    const processingExcluded = normalizeLearningApplications(input.processingExcludedApplications ?? previous.processingExcludedApplications ?? []);
+    const maturation = normalizeMaturationPolicy(input.maturation ?? previous.maturation ?? DEFAULT_MATURATION_POLICY);
+    const requestedConcurrency = input.maxConcurrentBatches ?? input.resourceLimits?.maxConcurrentCalls;
+    if (input.maxConcurrentBatches !== undefined && input.resourceLimits !== undefined &&
+        input.maxConcurrentBatches !== input.resourceLimits.maxConcurrentCalls)
+        throw new Error("invalid_learning_preferences");
+    const schedule = normalizeAnalysisSchedule({ ...input,
+        ...(requestedConcurrency === undefined ? {} : { maxConcurrentBatches: requestedConcurrency }) }, previous);
+    const resourceLimits = { ...(input.resourceLimits ?? previous.resourceLimits ?? DEFAULT_CO_WORKER_RESOURCE_LIMITS),
+        maxConcurrentCalls: schedule.maxConcurrentBatches ?? 1 };
+    validateCoWorkerResourceLimits(resourceLimits);
+    return Object.freeze({
+        ...(profile ? { modelProfileId: profile.trim() } : {}),
+        excludedApplications: excluded,
+        processingExcludedApplications: processingExcluded,
+        ...schedule,
+        ...normalizeIndependentLearningPreferences(input, previous),
+        ...normalizeLearningActivityControls(input, previous),
+        maturation: Object.freeze({ ...maturation }),
+        resourceLimits: Object.freeze({ ...resourceLimits }),
+    });
+}
+function parseState(value) {
+    if (!value || typeof value !== "object")
+        throw new Error("invalid_learning_state");
+    const root = value;
+    if (root.schemaVersion !== 1 ||
+        !root.preferences ||
+        typeof root.preferences !== "object" ||
+        !Array.isArray(root.batches))
+        throw new Error("invalid_learning_state");
+    const preferences = normalizeLearningPreferences({
+        ...root.preferences,
+        analysisIntervalMinutes: root.preferences.analysisIntervalMinutes ?? 5,
+        processingPaused: root.preferences.processingPaused ??
+            !root.preferences.enabled,
+    }, DEFAULT_LEARNING_PREFERENCES);
+    const batches = root.batches.map((item) => {
+        if (!item || typeof item !== "object")
+            throw new Error("invalid_learning_state");
+        const batch = item;
+        if (typeof batch.id !== "string" ||
+            typeof batch.generation !== "string" ||
+            !Number.isFinite(Date.parse(batch.createdAt)) ||
+            !Array.isArray(batch.observations) ||
+            !Array.isArray(batch.recordIds))
+            throw new Error("invalid_learning_state");
+        if (![
+            "pending",
+            "processing",
+            "saved",
+            "reviewed",
+            "discarded",
+            "failed",
+            "cancelled",
+        ].includes(batch.status))
+            throw new Error("invalid_learning_state");
+        const reviewProgress = readCoWorkerReviewProgress(batch.reviewProgress);
+        return { ...batch, ...(reviewProgress ? { reviewProgress } : {}) };
+    });
+    const observationReviewPass = readObservationReviewPass(root.observationReviewPass);
+    return { schemaVersion: 1, preferences, batches, ...(observationReviewPass ? { observationReviewPass } : {}) };
+}
+function isMissing(error) {
+    return (!!error &&
+        typeof error === "object" &&
+        "code" in error &&
+        error.code === "ENOENT");
+}

package/dist/src/runtime/plugins/compiled-catalog.d.ts

@@ -1,10 +1,11 @@
-import type { CanonicalToolDefinitionDeclaration, ToolCallAdapter, ToolImplementation } from "../../capabilities/tool-types.js";
+import type { CanonicalToolDefinitionDeclaration, ToolCallAdapter, ToolImplementation, ToolModuleRequestPreparation } from "../../capabilities/tool-types.js";
 import type { ToolNormalInvocationContract } from "../../capabilities/normal-invocation/contracts.js";
 export type CompiledPluginCapability = Readonly<{
     definition: CanonicalToolDefinitionDeclaration;
     normalInvocation: ToolNormalInvocationContract;
     execute: ToolImplementation;
     adapter?: ToolCallAdapter;
+    prepareRequest?: ToolModuleRequestPreparation;
 }>;
 export type CompiledRuntimePlugin = Readonly<{
     id: string;

package/dist/src/runtime/plugins/configured-manifests.d.ts

@@ -0,0 +1,3 @@
+import type { DiscoveredAgentPluginManifest } from "./discovered-manifest.js";
+import { type AgentPluginManifestDiscoveryOptions } from "./manifest-discovery.js";
+export declare function discoverConfiguredRuntimePluginManifests(consumerRoot: string, options?: AgentPluginManifestDiscoveryOptions): readonly DiscoveredAgentPluginManifest[];

package/dist/src/runtime/plugins/configured-manifests.js

@@ -0,0 +1,37 @@
+import { realpathSync } from "node:fs";
+import { resolve } from "node:path";
+import { discoverAgentPluginManifests, } from "./manifest-discovery.js";
+import { resolveBundledRuntimeRoot } from "./bundled-root.js";
+function canonicalPluginDiscoveryRoot(rootDir) {
+    const absoluteRoot = resolve(rootDir);
+    try {
+        return realpathSync(absoluteRoot);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT") {
+            throw error;
+        }
+        return absoluteRoot;
+    }
+}
+function assertUniquePluginManifestIds(plugins) {
+    const manifestPathsByPluginId = new Map();
+    for (const plugin of plugins) {
+        const pluginId = plugin.manifest.name;
+        const previousManifestPath = manifestPathsByPluginId.get(pluginId);
+        if (previousManifestPath) {
+            throw new Error(`Duplicate runtime plugin id: ${pluginId}; manifests: ${previousManifestPath}, ${plugin.manifestPath}`);
+        }
+        manifestPathsByPluginId.set(pluginId, plugin.manifestPath);
+    }
+}
+export function discoverConfiguredRuntimePluginManifests(consumerRoot, options = {}) {
+    const bundledRoot = resolveBundledRuntimeRoot();
+    const roots = canonicalPluginDiscoveryRoot(bundledRoot) ===
+        canonicalPluginDiscoveryRoot(consumerRoot)
+        ? [consumerRoot]
+        : [bundledRoot, consumerRoot];
+    const plugins = roots.flatMap((rootDir) => discoverAgentPluginManifests(rootDir, options));
+    assertUniquePluginManifestIds(plugins);
+    return Object.freeze(plugins);
+}

package/dist/src/runtime/plugins/entrypoint-validation.d.ts

@@ -0,0 +1,6 @@
+import type { RuntimePluginEntrypoint } from "../../plugin-contract/entrypoint.js";
+export declare function validateManifestEntrypoint(params: {
+    pluginId: string;
+    expectedCapabilityIds: readonly string[];
+    raw: unknown;
+}): RuntimePluginEntrypoint;

package/dist/src/runtime/plugins/entrypoint-validation.js

@@ -0,0 +1,74 @@
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+export function validateManifestEntrypoint(params) {
+    if (!isRecord(params.raw) || !isRecord(params.raw.handlers)) {
+        throw new Error(`Runtime plugin ${params.pluginId} entrypoint must export handlers`);
+    }
+    const unsupported = Object.keys(params.raw).find((key) => !["handlers", "adapters", "prepareRequest"].includes(key));
+    if (unsupported) {
+        throw new Error(`Runtime plugin ${params.pluginId} entrypoint contains unsupported field ${unsupported}`);
+    }
+    const handlers = validateEntrypointHandlers(params.pluginId, params.expectedCapabilityIds, params.raw.handlers);
+    const adapters = validateEntrypointAdapters(params.pluginId, params.expectedCapabilityIds, params.raw.adapters);
+    const prepareRequest = params.raw.prepareRequest;
+    if (!isOptionalEntrypointFunction(prepareRequest)) {
+        throw new Error(`Runtime plugin ${params.pluginId} prepareRequest must be a function`);
+    }
+    return {
+        handlers,
+        ...(prepareRequest
+            ? {
+                prepareRequest: prepareRequest,
+            }
+            : {}),
+        ...(Object.keys(adapters).length > 0 ? { adapters } : {}),
+    };
+}
+function validateEntrypointHandlers(pluginId, expectedCapabilityIds, raw) {
+    const handlers = {};
+    for (const [capabilityId, handler] of Object.entries(raw)) {
+        if (typeof handler !== "function") {
+            throw new Error(`Runtime plugin ${pluginId} handler ${capabilityId} must be a function`);
+        }
+        handlers[capabilityId] = handler;
+    }
+    const expected = new Set(expectedCapabilityIds);
+    const missing = expectedCapabilityIds.filter((id) => !handlers[id]);
+    const unexpected = Object.keys(handlers).filter((id) => !expected.has(id));
+    if (missing.length > 0 || unexpected.length > 0) {
+        throw new Error(`Runtime plugin ${pluginId} handler mismatch: missing=${missing.join(",") || "none"}; unexpected=${unexpected.join(",") || "none"}`);
+    }
+    return handlers;
+}
+function validateEntrypointAdapters(pluginId, expectedCapabilityIds, raw) {
+    if (raw === undefined)
+        return {};
+    if (!isRecord(raw)) {
+        throw new Error(`Runtime plugin ${pluginId} entrypoint adapters must be an object`);
+    }
+    const adapters = {};
+    for (const [capabilityId, adapter] of Object.entries(raw)) {
+        if (!expectedCapabilityIds.includes(capabilityId)) {
+            throw new Error(`Runtime plugin ${pluginId} adapter ${capabilityId} has no declared capability`);
+        }
+        adapters[capabilityId] = validateEntrypointAdapter(pluginId, capabilityId, adapter);
+    }
+    return adapters;
+}
+function validateEntrypointAdapter(pluginId, capabilityId, raw) {
+    const label = `Runtime plugin ${pluginId} adapter ${capabilityId}`;
+    if (!isRecord(raw))
+        throw new Error(`${label} must be an object`);
+    const fields = ["normalizeCall", "validateCall", "executionBinding"];
+    const unsupported = Object.keys(raw).find((key) => !fields.includes(key));
+    if (unsupported)
+        throw new Error(`${label} contains unsupported field ${unsupported}`);
+    const invalidFunction = fields.find((key) => !isOptionalEntrypointFunction(raw[key]));
+    if (invalidFunction)
+        throw new Error(`${label}.${invalidFunction} must be a function`);
+    return raw;
+}
+function isOptionalEntrypointFunction(value) {
+    return value === undefined || typeof value === "function";
+}

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

@@ -1,6 +1,6 @@
-import { realpathSync } from "node:fs";
+import { validateManifestEntrypoint } from "./entrypoint-validation.js";
 import { createRequire } from "node:module";
-import { join, resolve } from "node:path";
+import { join } from "node:path";
 import { createRuntimeToolPathResolver } from "../capabilities/runtime-target-path.js";
 import { validateToolModuleDeclarations } from "../../capabilities/tool-definition-validator.js";
 import { traceDebug } from "../observability/debug-logger.js";
@@ -8,42 +8,11 @@ import { ABOT_RUNTIME_EXTENSION } from "../../plugin-contract/manifest.js";
 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 { isPluginCatalogDisabled, isPluginToolSelected, normalizePluginSelection, pluginSelectionCacheKey, } from "./selection.js";
 const require = createRequire(import.meta.url);
 const compiledCatalogCache = new WeakMap();
 const bundledCatalogCache = new Map();
-function uniqueSorted(values) {
-    return [
-        ...new Set((values ?? [])
-            .map((value) => value.trim())
-            .filter((value) => value.length > 0)),
-    ].sort((left, right) => left.localeCompare(right));
-}
-function normalizePluginSelection(config) {
-    return Object.freeze({
-        enabled: config?.enabled !== false,
-        allow: Object.freeze(uniqueSorted(config?.allow)),
-        deny: Object.freeze(uniqueSorted(config?.deny)),
-    });
-}
-function pluginSelectionCacheKey(selection) {
-    return JSON.stringify([selection.enabled, selection.allow, selection.deny]);
-}
-function matchesPluginToolId(pluginId, toolName, configuredId) {
-    return (configuredId === "*" ||
-        configuredId === pluginId ||
-        configuredId === toolName ||
-        configuredId === `${pluginId}.${toolName}`);
-}
-function isPluginToolSelected(params) {
-    if (!params.selection.enabled) {
-        return false;
-    }
-    if (params.selection.allow.length > 0 &&
-        !params.selection.allow.some((entry) => matchesPluginToolId(params.pluginId, params.toolName, entry))) {
-        return false;
-    }
-    return !params.selection.deny.some((entry) => matchesPluginToolId(params.pluginId, params.toolName, entry));
-}
 function isRecord(value) {
     return !!value && typeof value === "object" && !Array.isArray(value);
 }
@@ -61,64 +30,12 @@ function unwrapPluginExport(rawModule) {
 function compiledCapabilityFromDeclaration(tool) {
     return {
         execute: tool.implementation,
+        ...(tool.prepareRequest ? { prepareRequest: tool.prepareRequest } : {}),
         ...(tool.adapter ? { adapter: tool.adapter } : {}),
         definition: tool.definition,
         normalInvocation: tool.normalInvocation,
     };
 }
-function validateManifestEntrypoint(params) {
-    if (!isRecord(params.raw) || !isRecord(params.raw.handlers)) {
-        throw new Error(`Runtime plugin ${params.pluginId} entrypoint must export handlers`);
-    }
-    const unexpectedEntrypointKeys = Object.keys(params.raw).filter((key) => key !== "handlers" && key !== "adapters");
-    if (unexpectedEntrypointKeys.length > 0) {
-        throw new Error(`Runtime plugin ${params.pluginId} entrypoint contains unsupported field ${unexpectedEntrypointKeys[0]}`);
-    }
-    const handlers = {};
-    for (const [capabilityId, handler] of Object.entries(params.raw.handlers)) {
-        if (typeof handler !== "function") {
-            throw new Error(`Runtime plugin ${params.pluginId} handler ${capabilityId} must be a function`);
-        }
-        handlers[capabilityId] = handler;
-    }
-    const expected = new Set(params.expectedCapabilityIds);
-    const missing = params.expectedCapabilityIds.filter((capabilityId) => !handlers[capabilityId]);
-    const unexpected = Object.keys(handlers).filter((capabilityId) => !expected.has(capabilityId));
-    if (missing.length > 0 || unexpected.length > 0) {
-        throw new Error(`Runtime plugin ${params.pluginId} handler mismatch: missing=${missing.join(",") || "none"}; unexpected=${unexpected.join(",") || "none"}`);
-    }
-    const adapters = {};
-    if (params.raw.adapters !== undefined) {
-        if (!isRecord(params.raw.adapters)) {
-            throw new Error(`Runtime plugin ${params.pluginId} entrypoint adapters must be an object`);
-        }
-        for (const [capabilityId, rawAdapter] of Object.entries(params.raw.adapters)) {
-            if (!expected.has(capabilityId)) {
-                throw new Error(`Runtime plugin ${params.pluginId} adapter ${capabilityId} has no declared capability`);
-            }
-            if (!isRecord(rawAdapter)) {
-                throw new Error(`Runtime plugin ${params.pluginId} adapter ${capabilityId} must be an object`);
-            }
-            const unexpectedAdapterKeys = Object.keys(rawAdapter).filter((key) => key !== "normalizeCall" && key !== "validateCall");
-            if (unexpectedAdapterKeys.length > 0) {
-                throw new Error(`Runtime plugin ${params.pluginId} adapter ${capabilityId} contains unsupported field ${unexpectedAdapterKeys[0]}`);
-            }
-            if (rawAdapter.normalizeCall !== undefined &&
-                typeof rawAdapter.normalizeCall !== "function") {
-                throw new Error(`Runtime plugin ${params.pluginId} adapter ${capabilityId}.normalizeCall must be a function`);
-            }
-            if (rawAdapter.validateCall !== undefined &&
-                typeof rawAdapter.validateCall !== "function") {
-                throw new Error(`Runtime plugin ${params.pluginId} adapter ${capabilityId}.validateCall must be a function`);
-            }
-            adapters[capabilityId] = rawAdapter;
-        }
-    }
-    return {
-        handlers,
-        ...(Object.keys(adapters).length > 0 ? { adapters } : {}),
-    };
-}
 function createManifestSecretAccessor(pluginId, declarations) {
     if (!declarations || Object.keys(declarations).length === 0) {
         return undefined;
@@ -180,6 +97,9 @@ function loadManifestRuntimePlugin(host, discovered, selectedCapabilityIds) {
         definition,
         normalInvocation,
         implementation: entrypoint.handlers[definition.name],
+        ...(entrypoint.prepareRequest
+            ? { prepareRequest: entrypoint.prepareRequest }
+            : {}),
         ...(entrypoint.adapters?.[definition.name]
             ? { adapter: entrypoint.adapters[definition.name] }
             : {}),
@@ -201,42 +121,9 @@ function loadManifestRuntimePlugin(host, discovered, selectedCapabilityIds) {
         capabilitySkills: projection.capabilitySkills,
     };
 }
-function canonicalPluginDiscoveryRoot(rootDir) {
-    const absoluteRoot = resolve(rootDir);
-    try {
-        return realpathSync(absoluteRoot);
-    }
-    catch (error) {
-        if (error.code !== "ENOENT") {
-            throw error;
-        }
-        return absoluteRoot;
-    }
-}
-function assertUniquePluginManifestIds(plugins) {
-    const manifestPathsByPluginId = new Map();
-    for (const plugin of plugins) {
-        const pluginId = plugin.manifest.name;
-        const previousManifestPath = manifestPathsByPluginId.get(pluginId);
-        if (previousManifestPath) {
-            throw new Error(`Duplicate runtime plugin id: ${pluginId}; manifests: ${previousManifestPath}, ${plugin.manifestPath}`);
-        }
-        manifestPathsByPluginId.set(pluginId, plugin.manifestPath);
-    }
-}
-function discoverConfiguredRuntimePluginManifests(consumerRoot) {
-    const bundledRoot = resolveBundledRuntimeRoot();
-    const roots = canonicalPluginDiscoveryRoot(bundledRoot) ===
-        canonicalPluginDiscoveryRoot(consumerRoot)
-        ? [consumerRoot]
-        : [bundledRoot, consumerRoot];
-    const plugins = roots.flatMap((rootDir) => discoverAgentPluginManifests(rootDir));
-    assertUniquePluginManifestIds(plugins);
-    return Object.freeze(plugins);
-}
 export function loadConfiguredRuntimePlugins(config) {
     const selection = normalizePluginSelection(config.plugins);
-    if (!selection.enabled) {
+    if (isPluginCatalogDisabled(selection)) {
         return [];
     }
     const cacheKey = pluginSelectionCacheKey(selection);
@@ -251,7 +138,7 @@ export function loadConfiguredRuntimePlugins(config) {
         agentBridgeUrl: config.agentBridgeUrl,
         runtimePaths: config.paths,
     };
-    const manifestPlugins = discoverConfiguredRuntimePluginManifests(config.paths.rootDir)
+    const manifestPlugins = discoverConfiguredRuntimePluginManifests(config.paths.rootDir, { excludedPluginIds: new Set(selection.deny) })
         .map((plugin) => ({
         plugin,
         selectedCapabilityIds: Object.keys(plugin.manifest.extensions[ABOT_RUNTIME_EXTENSION].capabilities).filter((capabilityId) => isPluginToolSelected({
@@ -330,6 +217,7 @@ export function runtimePluginsToToolModules(plugins) {
 function toolModuleDeclarationFromRuntimePlugin(tool) {
     return {
         implementation: tool.execute,
+        ...(tool.prepareRequest ? { prepareRequest: tool.prepareRequest } : {}),
         ...(tool.adapter ? { adapter: tool.adapter } : {}),
         definition: tool.definition,
         normalInvocation: tool.normalInvocation,

package/dist/src/runtime/plugins/manifest-discovery.d.ts

@@ -1,8 +1,11 @@
 import type { DiscoveredAgentPluginManifest } from "./discovered-manifest.js";
+export type AgentPluginManifestDiscoveryOptions = Readonly<{
+    excludedPluginIds?: ReadonlySet<string>;
+}>;
 export declare function resolveContainedPluginFile(params: {
     pluginRoot: string;
     configuredPath: string;
     label: string;
 }): string;
 export declare function readAgentPluginSkills(plugin: DiscoveredAgentPluginManifest, selectedSkillNames?: ReadonlySet<string>): Record<string, string>;
-export declare function discoverAgentPluginManifests(rootDir: string): DiscoveredAgentPluginManifest[];
+export declare function discoverAgentPluginManifests(rootDir: string, options?: AgentPluginManifestDiscoveryOptions): DiscoveredAgentPluginManifest[];

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

@@ -2,6 +2,9 @@ import { existsSync, readFileSync, readdirSync, realpathSync, statSync, } from "
 import { isAbsolute, join, relative, resolve } from "node:path";
 import { traceDebug } from "../observability/debug-logger.js";
 import { parseAgentPluginManifest } from "./manifest-validator.js";
+function isPluginManifestExcluded(pluginId, options) {
+    return options.excludedPluginIds?.has(pluginId) ?? false;
+}
 function isContained(root, candidate) {
     const relativePath = relative(root, candidate);
     return (relativePath === "" ||
@@ -62,7 +65,7 @@ export function readAgentPluginSkills(plugin, selectedSkillNames) {
     }
     return skills;
 }
-export function discoverAgentPluginManifests(rootDir) {
+export function discoverAgentPluginManifests(rootDir, options = {}) {
     const pluginsPath = resolve(rootDir, "plugins");
     traceDebug("runtime.plugins", "manifest_discovery.started", {
         pluginsPath,
@@ -80,6 +83,10 @@ export function discoverAgentPluginManifests(rootDir) {
     }).sort((left, right) => left.name.localeCompare(right.name));
     const discovered = [];
     for (const entry of entries) {
+        // A valid manifest must use its directory name as the plugin ID. An
+        // explicitly denied package needs no filesystem traversal or validation.
+        if (isPluginManifestExcluded(entry.name, options))
+            continue;
         const candidateRoot = join(resolvedPluginsPath, entry.name);
         if (!statSync(candidateRoot).isDirectory()) {
             continue;

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

@@ -40,6 +40,9 @@ export function projectManifestRuntimeContract(discovered, selectedCapabilityIds
         declarations.push({
             definition: {
                 name: capabilityId,
+                ...(capability.requiredPermissionMode
+                    ? { requiredPermissionMode: capability.requiredPermissionMode }
+                    : {}),
                 description: capability.description,
                 routingCapability: capability.routingCapability,
                 ...(capability.controlsRefinement

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

@@ -1,5 +1,7 @@
+import { parseRequiredToolPermissionMode } from "../../capabilities/tool-permission-mode.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";
 import { ABOT_RUNTIME_EXTENSION, ABOT_RUNTIME_EXTENSION_VERSION, AGENT_PLUGIN_MANIFEST_SCHEMA, } from "../../plugin-contract/manifest.js";
 const PLUGIN_NAME_PATTERN = /^(?!.*(?:--|\.\.))[a-z0-9][a-z0-9.-]{0,62}[a-z0-9]$|^[a-z0-9]$/u;
 const SECRET_ENV_PATTERN = /^[A-Z][A-Z0-9_]*$/u;
@@ -20,6 +22,7 @@ const DEVELOPMENT_ROLES = [
 const EVENT_PROJECTION_KINDS = [
     "string",
     "number",
+    "boolean",
     "string_array",
     "length",
 ];
@@ -211,7 +214,7 @@ function parseEventPresentation(value, path) {
                 throw new Error(`${path}.metadata contains an empty key`);
             }
             const projection = expectRecord(rawProjection, `${path}.metadata.${key}`);
-            rejectUnknownKeys(projection, ["param", "kind", "default"], `${path}.metadata.${key}`);
+            rejectUnknownKeys(projection, ["param", "kind", "default", "maxLength", "preserveWhitespace"], `${path}.metadata.${key}`);
             if (!nonEmptyString(projection.param)) {
                 throw new Error(`${path}.metadata.${key}.param must be non-empty`);
             }
@@ -228,6 +231,7 @@ function parseEventPresentation(value, path) {
             return [
                 key,
                 {
+                    ...parseEventInputTextOptions(projection, `${path}.metadata.${key}`),
                     param: projection.param.trim(),
                     kind: projection.kind,
                     ...(fallback !== undefined ? { default: fallback } : {}),
@@ -349,6 +353,7 @@ function parseCapabilities(value, path) {
         }
         const capability = expectRecord(rawCapability, `${path}.${capabilityId}`);
         rejectUnknownKeys(capability, [
+            "requiredPermissionMode",
             "description",
             "routingCapability",
             "controlsRefinement",
@@ -393,6 +398,7 @@ function parseCapabilities(value, path) {
         return [
             capabilityId,
             {
+                requiredPermissionMode: parseRequiredToolPermissionMode(capability.requiredPermissionMode, `${path}.${capabilityId}.requiredPermissionMode`),
                 description: capability.description.trim(),
                 routingCapability: capability.routingCapability,
                 ...(controlsRefinement === "mechanical_when_complete"

package/dist/src/runtime/plugins/runtime-capability-plugins.d.ts

@@ -0,0 +1,4 @@
+import type { RuntimeConfig } from "../ports.js";
+import type { CompiledRuntimePlugin } from "./compiled-catalog.js";
+/** Tools and skills share the same selected catalog and compiled instances. */
+export declare function loadRuntimeCapabilityPlugins(config?: RuntimeConfig): readonly CompiledRuntimePlugin[];

package/dist/src/runtime/plugins/runtime-capability-plugins.js

@@ -0,0 +1,7 @@
+import { loadBundledRuntimePlugins, loadConfiguredRuntimePlugins, } from "./loader.js";
+/** Tools and skills share the same selected catalog and compiled instances. */
+export function loadRuntimeCapabilityPlugins(config) {
+    return config
+        ? loadConfiguredRuntimePlugins(config)
+        : loadBundledRuntimePlugins();
+}

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

@@ -0,0 +1,14 @@
+import type { RuntimePluginConfig } from "../ports.js";
+export type PluginSelection = Readonly<{
+    enabled: boolean;
+    allow: readonly string[];
+    deny: readonly string[];
+}>;
+export declare function normalizePluginSelection(config: RuntimePluginConfig | undefined): PluginSelection;
+export declare function pluginSelectionCacheKey(selection: PluginSelection): string;
+export declare function isPluginCatalogDisabled(selection: PluginSelection): boolean;
+export declare function isPluginToolSelected(params: {
+    pluginId: string;
+    toolName: string;
+    selection: PluginSelection;
+}): boolean;

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

@@ -0,0 +1,38 @@
+function uniqueSorted(values) {
+    return [
+        ...new Set((values ?? [])
+            .map((value) => value.trim())
+            .filter((value) => value.length > 0)),
+    ].sort((left, right) => left.localeCompare(right));
+}
+export function normalizePluginSelection(config) {
+    return Object.freeze({
+        enabled: config?.enabled !== false,
+        allow: Object.freeze(uniqueSorted(config?.allow)),
+        deny: Object.freeze(uniqueSorted(config?.deny)),
+    });
+}
+export function pluginSelectionCacheKey(selection) {
+    return JSON.stringify([selection.enabled, selection.allow, selection.deny]);
+}
+export function isPluginCatalogDisabled(selection) {
+    if (!selection.enabled)
+        return true;
+    return selection.deny.includes("*");
+}
+function matchesPluginToolId(pluginId, toolName, configuredId) {
+    return (configuredId === "*" ||
+        configuredId === pluginId ||
+        configuredId === toolName ||
+        configuredId === `${pluginId}.${toolName}`);
+}
+export function isPluginToolSelected(params) {
+    if (!params.selection.enabled) {
+        return false;
+    }
+    if (params.selection.allow.length > 0 &&
+        !params.selection.allow.some((entry) => matchesPluginToolId(params.pluginId, params.toolName, entry))) {
+        return false;
+    }
+    return !params.selection.deny.some((entry) => matchesPluginToolId(params.pluginId, params.toolName, entry));
+}