@elizaos/shared 2.0.0-alpha.538 → 2.0.11-beta.7

package/config/plugin-manifest.js

@@ -0,0 +1,281 @@
+// Plugin manifest evaluation engine.
+//
+// Each plugin declares its auto-enable conditions in its package.json under
+// `elizaos.plugin`, optionally pointing at a small JS module that implements
+// the actual `shouldEnable(ctx)` check:
+//
+//   {
+//     "elizaos": {
+//       "plugin": {
+//         "autoEnableModule": "./dist/auto-enable.js",
+//         "force": false,
+//         "capabilities": ["text-large", "tool-use"]
+//       }
+//     }
+//   }
+//
+// The check module exports:
+//
+//   export function shouldEnable(ctx: PluginAutoEnableContext): boolean | Promise<boolean>;
+//   export function shouldForce?(ctx: PluginAutoEnableContext): boolean;  // optional override
+//
+// The engine here:
+//   1. Walks a list of candidate plugin packages.
+//   2. Reads each package.json for the elizaos.plugin block.
+//   3. Dynamic-imports the autoEnableModule (cheap if it stays small — convention,
+//      not enforced; consumers can lint via knip or import-graph if drift becomes a problem).
+//   4. Evaluates shouldEnable + shouldForce against the runtime context.
+//   5. Returns a verdict per plugin.
+//
+// This replaces the centralized maps in plugin-auto-enable-engine.ts. Both
+// engines coexist during the migration: the new one runs first, the old one
+// fills gaps for plugins that haven't migrated yet. When all plugins ship a
+// manifest, the central maps and the old engine can be deleted.
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+function assertPackageJsonObject(value, packageRoot) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`invalid package.json object at ${packageRoot}`);
+    }
+}
+/**
+ * Derive the short id used for `plugins.allow` and `plugins.entries` lookups.
+ * Mirrors the logic in plugin-auto-enable-engine.addToAllowlist.
+ */
+export function pluginShortId(packageName) {
+    if (packageName === "@elizaos/plugin-companion") {
+        return packageName;
+    }
+    return packageName.includes("/plugin-")
+        ? packageName.slice(packageName.lastIndexOf("/plugin-") + "/plugin-".length)
+        : packageName;
+}
+/**
+ * Read `package.json` for a candidate and extract the elizaos.plugin block.
+ * Returns null when no package.json exists or it doesn't declare an elizaos.plugin block.
+ */
+export async function readPluginPackageManifest(packageRoot) {
+    let raw;
+    try {
+        raw = await fs.readFile(path.join(packageRoot, "package.json"), "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+    const parsed = JSON.parse(raw);
+    assertPackageJsonObject(parsed, packageRoot);
+    if (!parsed.elizaos?.plugin)
+        return null;
+    return parsed;
+}
+const CHECK_MODULE_CACHE = new Map();
+/**
+ * Dynamic-import the check module declared by a manifest. Cached per absolute
+ * module path so re-evaluation across multiple boots in the same process
+ * (e.g. test suites) doesn't re-import.
+ */
+async function loadCheckModule(packageRoot, modulePath) {
+    const absolute = path.resolve(packageRoot, modulePath);
+    const cached = CHECK_MODULE_CACHE.get(absolute);
+    if (cached === "missing")
+        return null;
+    if (cached)
+        return cached;
+    try {
+        await fs.access(absolute);
+    }
+    catch {
+        CHECK_MODULE_CACHE.set(absolute, "missing");
+        return null;
+    }
+    const url = pathToFileURL(absolute).href;
+    // Dynamic file:// import — Vite's static analyzer flags this on the client
+    // bundle even though the engine only runs server-side at boot. Suppress.
+    const mod = (await import(__rewriteRelativeImportExtension(
+    /* @vite-ignore */ url)));
+    // Accept both named and default exports — `export function shouldEnable`
+    // and `export default { shouldEnable }` both work.
+    const resolved = typeof mod.shouldEnable === "function"
+        ? { shouldEnable: mod.shouldEnable, shouldForce: mod.shouldForce }
+        : typeof mod.default?.shouldEnable === "function"
+            ? {
+                shouldEnable: mod.default.shouldEnable,
+                shouldForce: mod.default.shouldForce,
+            }
+            : null;
+    if (!resolved) {
+        CHECK_MODULE_CACHE.set(absolute, "missing");
+        return null;
+    }
+    CHECK_MODULE_CACHE.set(absolute, resolved);
+    return resolved;
+}
+/**
+ * Evaluate one candidate's manifest against the runtime context. Pure
+ * verdict — caller decides how to apply it to the allow list / force overrides.
+ */
+export async function evaluatePluginManifest(candidate, ctx) {
+    const manifest = await readPluginPackageManifest(candidate.packageRoot);
+    if (!manifest)
+        return null;
+    const block = manifest.elizaos?.plugin ?? {};
+    const shortId = pluginShortId(candidate.packageName);
+    const capabilities = Array.isArray(block.capabilities)
+        ? block.capabilities.filter((c) => typeof c === "string")
+        : [];
+    if (!block.autoEnableModule) {
+        // Manifest exists but no check module — treat as not-auto-enabled (the
+        // plugin can still be enabled via explicit user config). Still surface
+        // declared capabilities.
+        return {
+            packageName: candidate.packageName,
+            shortId,
+            enabled: false,
+            force: block.force === true,
+            capabilities,
+            reason: null,
+            error: null,
+        };
+    }
+    let module;
+    try {
+        module = await loadCheckModule(candidate.packageRoot, block.autoEnableModule);
+    }
+    catch (err) {
+        return {
+            packageName: candidate.packageName,
+            shortId,
+            enabled: false,
+            force: block.force === true,
+            capabilities,
+            reason: null,
+            error: `failed to import autoEnableModule "${block.autoEnableModule}": ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    if (!module) {
+        return {
+            packageName: candidate.packageName,
+            shortId,
+            enabled: false,
+            force: block.force === true,
+            capabilities,
+            reason: null,
+            error: `autoEnableModule "${block.autoEnableModule}" did not export a shouldEnable function`,
+        };
+    }
+    let enabled;
+    try {
+        enabled = Boolean(await module.shouldEnable(ctx));
+    }
+    catch (err) {
+        return {
+            packageName: candidate.packageName,
+            shortId,
+            enabled: false,
+            force: block.force === true,
+            capabilities,
+            reason: null,
+            error: `shouldEnable threw: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    let force = block.force === true;
+    if (module.shouldForce) {
+        try {
+            force = force || Boolean(module.shouldForce(ctx));
+        }
+        catch {
+            // Treat predicate failure as "no force" — don't escalate.
+            force = block.force === true;
+        }
+    }
+    return {
+        packageName: candidate.packageName,
+        shortId,
+        enabled,
+        force,
+        capabilities,
+        reason: enabled || force
+            ? `manifest: ${candidate.packageName}/${block.autoEnableModule}`
+            : null,
+        error: null,
+    };
+}
+/**
+ * Evaluate every candidate. Verdicts come back in the same order as the input.
+ * Failures are reported in the verdict's `error` field — this function never
+ * throws so a single bad manifest can't kill auto-enable for the rest.
+ */
+export async function evaluatePluginManifests(candidates, ctx) {
+    return Promise.all(candidates.map(async (candidate) => {
+        try {
+            return await evaluatePluginManifest(candidate, ctx);
+        }
+        catch (err) {
+            return {
+                packageName: candidate.packageName,
+                shortId: pluginShortId(candidate.packageName),
+                enabled: false,
+                force: false,
+                capabilities: [],
+                reason: null,
+                error: `manifest read failed: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+    })).then((entries) => entries.filter((v) => v !== null));
+}
+/**
+ * Apply manifest verdicts to a config: push enabled plugins onto
+ * `plugins.allow` (with the short id and full package name), set
+ * `plugins.entries[shortId].enabled = true` for forced ones, and append
+ * human-readable strings to `changes` for log surfacing.
+ */
+export function applyPluginManifestVerdicts(config, verdicts, changes) {
+    config.plugins = config.plugins ?? {};
+    const pluginsConfig = config.plugins;
+    pluginsConfig.allow = pluginsConfig.allow ?? [];
+    pluginsConfig.entries = pluginsConfig.entries ?? {};
+    for (const verdict of verdicts) {
+        if (verdict.error) {
+            changes.push(`Plugin auto-enable error for ${verdict.packageName}: ${verdict.error}`);
+            continue;
+        }
+        if (!verdict.enabled && !verdict.force)
+            continue;
+        const explicitlyDisabled = pluginsConfig.entries[verdict.shortId]?.enabled === false;
+        if (explicitlyDisabled && !verdict.force) {
+            // User explicitly disabled — respect that unless force is set.
+            continue;
+        }
+        if (verdict.force && explicitlyDisabled) {
+            pluginsConfig.entries[verdict.shortId] = {
+                ...pluginsConfig.entries[verdict.shortId],
+                enabled: true,
+            };
+        }
+        let added = false;
+        if (!pluginsConfig.allow.includes(verdict.shortId)) {
+            pluginsConfig.allow.push(verdict.shortId);
+            added = true;
+        }
+        if (verdict.packageName !== verdict.shortId &&
+            !pluginsConfig.allow.includes(verdict.packageName)) {
+            pluginsConfig.allow.push(verdict.packageName);
+            added = true;
+        }
+        if (added && verdict.reason) {
+            changes.push(`Auto-enabled plugin: ${verdict.packageName} (${verdict.reason})`);
+        }
+    }
+}
+//# sourceMappingURL=plugin-manifest.js.map

package/config/plugin-manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-manifest.js","sourceRoot":"","sources":["../../src/config/plugin-manifest.ts"],"names":[],"mappings":"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"}

package/config/plugin-ui-spec.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Generates UiSpec JSON for plugin/connector configuration forms.
+ *
+ * When the agent wants to help a user configure a plugin, it generates
+ * a UiSpec that renders as an interactive form in chat. The form fields
+ * are derived from the plugin's parameter definitions.
+ *
+ * Actions:
+ *   - "plugin:save" → saves config via PUT /api/plugins/:id
+ *   - "plugin:enable" → enables the plugin
+ *   - "plugin:test" → tests connectivity
+ */
+export interface PluginParam {
+    key: string;
+    required?: boolean;
+    isSet?: boolean;
+    type?: string;
+    description?: string;
+    label?: string;
+}
+export interface PluginForUiSpec {
+    id: string;
+    name: string;
+    description?: string;
+    enabled?: boolean;
+    category?: string;
+    parameters: PluginParam[];
+}
+/** Declarative UI specification for rendering plugin forms in chat. */
+export interface PluginUiSpec {
+    version: number;
+    root: string;
+    elements: Record<string, Record<string, unknown>>;
+    state: Record<string, unknown>;
+}
+export declare function buildPluginConfigUiSpec(plugin: PluginForUiSpec): PluginUiSpec;
+/**
+ * Generate a compact plugin list UiSpec for the agent to show available
+ * plugins matching a query.
+ */
+export declare function buildPluginListUiSpec(plugins: PluginForUiSpec[], title: string): PluginUiSpec;
+//# sourceMappingURL=plugin-ui-spec.d.ts.map

package/config/plugin-ui-spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-ui-spec.d.ts","sourceRoot":"","sources":["../../src/config/plugin-ui-spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,WAAW,EAAE,CAAC;CAC3B;AAED,uEAAuE;AACvE,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAClD,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,eAAe,GAAG,YAAY,CAuL7E;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,eAAe,EAAE,EAC1B,KAAK,EAAE,MAAM,GACZ,YAAY,CA+Ed"}

package/config/plugin-ui-spec.js

@@ -0,0 +1,257 @@
+/**
+ * Generates UiSpec JSON for plugin/connector configuration forms.
+ *
+ * When the agent wants to help a user configure a plugin, it generates
+ * a UiSpec that renders as an interactive form in chat. The form fields
+ * are derived from the plugin's parameter definitions.
+ *
+ * Actions:
+ *   - "plugin:save" → saves config via PUT /api/plugins/:id
+ *   - "plugin:enable" → enables the plugin
+ *   - "plugin:test" → tests connectivity
+ */
+export function buildPluginConfigUiSpec(plugin) {
+    const elements = {};
+    const rootChildren = [];
+    const state = {
+        pluginId: plugin.id,
+    };
+    // Header
+    elements.header = {
+        type: "Stack",
+        props: { gap: "1", children: ["title", "desc"] },
+    };
+    rootChildren.push("header");
+    elements.title = {
+        type: "Heading",
+        props: {
+            level: 3,
+            text: `Configure ${plugin.name}`,
+        },
+    };
+    if (plugin.description) {
+        elements.desc = {
+            type: "Text",
+            props: {
+                text: plugin.description,
+                className: "text-xs text-muted",
+            },
+        };
+    }
+    // Status badge
+    const statusText = plugin.enabled
+        ? plugin.parameters.every((p) => !p.required || p.isSet)
+            ? "Ready"
+            : "Needs Configuration"
+        : "Disabled";
+    const statusVariant = plugin.enabled
+        ? plugin.parameters.every((p) => !p.required || p.isSet)
+            ? "default"
+            : "secondary"
+        : "outline";
+    elements.status = {
+        type: "Badge",
+        props: { text: statusText, variant: statusVariant },
+    };
+    rootChildren.push("status");
+    // Separator
+    elements.sep = { type: "Separator", props: {} };
+    rootChildren.push("sep");
+    // Parameter fields
+    const fieldIds = [];
+    for (const param of plugin.parameters) {
+        const fieldId = `field_${param.key}`;
+        const statePath = `config.${param.key}`;
+        fieldIds.push(fieldId);
+        state[`config.${param.key}`] = "";
+        const isSecret = param.key.includes("KEY") ||
+            param.key.includes("TOKEN") ||
+            param.key.includes("SECRET") ||
+            param.key.includes("PASSWORD");
+        elements[fieldId] = {
+            type: "Input",
+            props: {
+                label: param.label || param.key,
+                placeholder: param.isSet
+                    ? "••••••• (already set)"
+                    : param.required
+                        ? "Required"
+                        : "Optional",
+                statePath,
+                type: isSecret ? "password" : "text",
+                className: "font-mono text-xs",
+            },
+            ...(param.required
+                ? {
+                    validation: {
+                        checks: [
+                            { rule: "required", message: `${param.key} is required` },
+                        ],
+                    },
+                }
+                : {}),
+        };
+        // Add description below field if available
+        if (param.description) {
+            const hintId = `hint_${param.key}`;
+            fieldIds.push(hintId);
+            elements[hintId] = {
+                type: "Text",
+                props: {
+                    text: param.description,
+                    className: "text-2xs text-muted -mt-1 mb-1",
+                },
+            };
+        }
+    }
+    elements.fields = {
+        type: "Stack",
+        props: { gap: "3", children: fieldIds },
+    };
+    rootChildren.push("fields");
+    // Action buttons
+    const buttonChildren = ["saveBtn"];
+    elements.saveBtn = {
+        type: "Button",
+        props: {
+            text: "Save Configuration",
+            variant: "default",
+            className: "font-semibold",
+            on: {
+                press: {
+                    action: "plugin:save",
+                    params: { pluginId: plugin.id },
+                },
+            },
+        },
+    };
+    if (!plugin.enabled) {
+        buttonChildren.push("enableBtn");
+        elements.enableBtn = {
+            type: "Button",
+            props: {
+                text: "Enable Plugin",
+                variant: "outline",
+                on: {
+                    press: {
+                        action: "plugin:enable",
+                        params: { pluginId: plugin.id },
+                    },
+                },
+            },
+        };
+    }
+    if (plugin.category === "connector") {
+        buttonChildren.push("testBtn");
+        elements.testBtn = {
+            type: "Button",
+            props: {
+                text: "Test Connection",
+                variant: "outline",
+                on: {
+                    press: {
+                        action: "plugin:test",
+                        params: { pluginId: plugin.id },
+                    },
+                },
+            },
+        };
+    }
+    elements.actions = {
+        type: "Stack",
+        props: { direction: "row", gap: "2", children: buttonChildren },
+    };
+    rootChildren.push("actions");
+    // Root
+    elements.root = {
+        type: "Card",
+        props: {
+            children: rootChildren,
+            className: "p-4 space-y-3",
+        },
+    };
+    return {
+        version: 1,
+        root: "root",
+        elements,
+        state,
+    };
+}
+/**
+ * Generate a compact plugin list UiSpec for the agent to show available
+ * plugins matching a query.
+ */
+export function buildPluginListUiSpec(plugins, title) {
+    const elements = {};
+    const cardIds = [];
+    elements.heading = {
+        type: "Heading",
+        props: { level: 3, text: title },
+    };
+    for (let i = 0; i < plugins.length; i++) {
+        const p = plugins[i];
+        const cardId = `card_${i}`;
+        const nameId = `name_${i}`;
+        const descId = `desc_${i}`;
+        const badgeId = `badge_${i}`;
+        const configBtnId = `cfgBtn_${i}`;
+        cardIds.push(cardId);
+        elements[nameId] = {
+            type: "Text",
+            props: {
+                text: p.name,
+                className: "font-semibold text-sm",
+            },
+        };
+        elements[descId] = {
+            type: "Text",
+            props: {
+                text: p.description || "No description",
+                className: "text-xs text-muted",
+            },
+        };
+        elements[badgeId] = {
+            type: "Badge",
+            props: {
+                text: p.enabled ? "Enabled" : "Available",
+                variant: p.enabled ? "default" : "outline",
+            },
+        };
+        elements[configBtnId] = {
+            type: "Button",
+            props: {
+                text: "Configure",
+                variant: "outline",
+                size: "sm",
+                on: {
+                    press: {
+                        action: "plugin:configure",
+                        params: { pluginId: p.id },
+                    },
+                },
+            },
+        };
+        elements[cardId] = {
+            type: "Card",
+            props: {
+                children: [nameId, descId, badgeId, configBtnId],
+                className: "p-3 space-y-1",
+            },
+        };
+    }
+    elements.list = {
+        type: "Stack",
+        props: { gap: "2", children: cardIds },
+    };
+    elements.root = {
+        type: "Stack",
+        props: { gap: "3", children: ["heading", "list"] },
+    };
+    return {
+        version: 1,
+        root: "root",
+        elements,
+        state: {},
+    };
+}
+//# sourceMappingURL=plugin-ui-spec.js.map

package/config/plugin-ui-spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-ui-spec.js","sourceRoot":"","sources":["../../src/config/plugin-ui-spec.ts"],"names":[],"mappings":"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"}

package/config/runtime-mode.d.ts

@@ -0,0 +1,54 @@
+import type { DeploymentTargetConfig } from "../contracts/service-routing.js";
+export declare const RUNTIME_EXECUTION_MODES: readonly ["cloud", "local-safe", "local-yolo"];
+export type RuntimeExecutionMode = (typeof RUNTIME_EXECUTION_MODES)[number];
+export interface RuntimeModeConfig {
+    executionMode?: RuntimeExecutionMode;
+}
+export interface RuntimeExecutionModeConfigSource {
+    runtime?: RuntimeModeConfig | Record<string, unknown> | null;
+    deploymentTarget?: DeploymentTargetConfig | null;
+}
+export interface RuntimeExecutionModeDefinition {
+    mode: RuntimeExecutionMode;
+    local: boolean;
+    cloud: boolean;
+    safe: boolean;
+    yolo: boolean;
+}
+export declare const RUNTIME_EXECUTION_MODE_DEFINITIONS: Record<RuntimeExecutionMode, RuntimeExecutionModeDefinition>;
+export declare function normalizeRuntimeExecutionMode(value: unknown): RuntimeExecutionMode | null;
+export declare function isCloudRuntimeMode(value: unknown): boolean;
+export declare function isLocalRuntimeMode(value: unknown): boolean;
+export declare function isSafeLocalMode(value: unknown): boolean;
+export declare function isYoloLocalMode(value: unknown): boolean;
+export declare function runtimeExecutionModeForDeploymentTarget(deploymentTarget: DeploymentTargetConfig | null | undefined): RuntimeExecutionMode;
+export declare function readRuntimeExecutionModeConfig(config: RuntimeExecutionModeConfigSource | null | undefined): RuntimeExecutionMode;
+/**
+ * Structural shape for the runtime/setting source consumed by the env-driven
+ * resolvers below. Kept structural so this module does not have to import
+ * `IAgentRuntime` from `@elizaos/core` (which would create a layering wart —
+ * runtime/agent types depend on this module, not the other way around).
+ */
+export interface RuntimeExecutionModeSource {
+    getSetting?: (key: string) => unknown;
+}
+/**
+ * Canonical resolver for the active runtime execution mode at the
+ * agent/plugin boundary. Reads an explicit setting from the runtime first,
+ * then falls back to the same env vars, defaulting to `local-yolo` when
+ * nothing is set.
+ *
+ * This is the one source of truth for `cloud | local-safe | local-yolo`
+ * routing; both the agent package and the shell/coding-tools plugins import
+ * it from `@elizaos/shared` to avoid duplicating the resolution logic.
+ */
+export declare function resolveRuntimeExecutionMode(source?: RuntimeExecutionModeSource | null): RuntimeExecutionMode;
+/** Local-only narrowing of {@link RuntimeExecutionMode} for callers that only
+ * distinguish local-safe vs local-yolo. Cloud collapses to `local-yolo` here
+ * because legacy callers used this helper to pick a host-side execution path
+ * and only flipped to safe-mode when the sandbox was required. */
+export type LocalExecutionMode = "local-safe" | "local-yolo";
+export declare function resolveLocalExecutionMode(source?: RuntimeExecutionModeSource | null): LocalExecutionMode;
+export declare function shouldUseSandboxExecution(source?: RuntimeExecutionModeSource | null): boolean;
+export declare function isCloudExecutionMode(source?: RuntimeExecutionModeSource | null): boolean;
+//# sourceMappingURL=runtime-mode.d.ts.map

package/config/runtime-mode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-mode.d.ts","sourceRoot":"","sources":["../../src/config/runtime-mode.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAI9E,eAAO,MAAM,uBAAuB,gDAI1B,CAAC;AAEX,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5E,MAAM,WAAW,iBAAiB;IAChC,aAAa,CAAC,EAAE,oBAAoB,CAAC;CACtC;AAED,MAAM,WAAW,gCAAgC;IAC/C,OAAO,CAAC,EAAE,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC7D,gBAAgB,CAAC,EAAE,sBAAsB,GAAG,IAAI,CAAC;CAClD;AAED,MAAM,WAAW,8BAA8B;IAC7C,IAAI,EAAE,oBAAoB,CAAC;IAC3B,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;CACf;AAED,eAAO,MAAM,kCAAkC,EAAE,MAAM,CACrD,oBAAoB,EACpB,8BAA8B,CAuB/B,CAAC;AAEF,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,OAAO,GACb,oBAAoB,GAAG,IAAI,CAM7B;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE1D;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAG1D;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEvD;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEvD;AAED,wBAAgB,uCAAuC,CACrD,gBAAgB,EAAE,sBAAsB,GAAG,IAAI,GAAG,SAAS,GAC1D,oBAAoB,CAEtB;AAED,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,gCAAgC,GAAG,IAAI,GAAG,SAAS,GAC1D,oBAAoB,CAYtB;AAED;;;;;GAKG;AACH,MAAM,WAAW,0BAA0B;IACzC,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;CACvC;AAQD;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,CAAC,EAAE,0BAA0B,GAAG,IAAI,GACzC,oBAAoB,CAoBtB;AAED;;;kEAGkE;AAClE,MAAM,MAAM,kBAAkB,GAAG,YAAY,GAAG,YAAY,CAAC;AAE7D,wBAAgB,yBAAyB,CACvC,MAAM,CAAC,EAAE,0BAA0B,GAAG,IAAI,GACzC,kBAAkB,CAIpB;AAED,wBAAgB,yBAAyB,CACvC,MAAM,CAAC,EAAE,0BAA0B,GAAG,IAAI,GACzC,OAAO,CAET;AAED,wBAAgB,oBAAoB,CAClC,MAAM,CAAC,EAAE,0BAA0B,GAAG,IAAI,GACzC,OAAO,CAET"}