@framers/agentos 0.1.0

package/dist/core/tools/permissions/IToolPermissionManager.d.ts

@@ -0,0 +1,195 @@
+/**
+ * @fileoverview Defines the IToolPermissionManager interface, responsible for
+ * determining if a tool execution is authorized based on various criteria such as
+ * Persona capabilities, user subscriptions, and potentially other contextual rules.
+ *
+ * @module backend/agentos/core/tools/IToolPermissionManager
+ * @see ./ITool.ts for ITool definition (which includes requiredCapabilities).
+ * @see ../cognitive_substrate/IGMI.ts for UserContext.
+ * @see ../../../../services/user_auth/IAuthService.ts for authentication context.
+ * @see ../../../../services/user_auth/SubscriptionService.ts for subscription and feature flags.
+ */
+import { ITool } from '../ITool';
+import { UserContext } from '../../../cognitive_substrate/IGMI';
+import type { IAuthService, ISubscriptionService } from '../../../services/user_auth/types';
+/**
+ * @interface FeatureFlag
+ * @description Defines the structure for a feature flag, used to gate access to tools
+ * based on user subscriptions or specific entitlements.
+ *
+ * @property {string} flag - The unique string identifier for the feature flag (e.g., "CAN_USE_ADVANCED_SEARCH_TOOL").
+ * @property {string} [description] - Optional. A human-readable description of the feature.
+ */
+export interface FeatureFlag {
+    flag: string;
+    description?: string;
+}
+/**
+ * Represents the context required for making a permission decision for tool usage.
+ * This object aggregates all necessary information that the `IToolPermissionManager`
+ * needs to evaluate whether a tool call should be allowed.
+ *
+ * @interface PermissionCheckContext
+ * @property {ITool} tool - The actual `ITool` instance for which permission is being checked.
+ * This provides access to tool metadata like `id`, `name`, and `requiredCapabilities`.
+ * @property {string} personaId - The unique identifier of the active Persona within the GMI
+ * that is attempting to use the tool.
+ * @property {string[]} personaCapabilities - An array of capability strings (e.g., "filesystem:read", "api:weather")
+ * currently possessed by the active Persona.
+ * @property {UserContext} userContext - The context of the end-user associated with the current request,
+ * which may include `userId`, preferences, skill level, etc.
+ * @property {string} [gmiId] - Optional. The unique identifier of the GMI instance making the request.
+ * Useful for logging or more granular GMI-specific rules.
+ */
+export interface PermissionCheckContext {
+    tool: ITool;
+    personaId: string;
+    personaCapabilities: string[];
+    userContext: UserContext;
+    gmiId?: string;
+}
+/**
+ * Represents the result of a permission check performed by the `IToolPermissionManager`.
+ *
+ * @interface PermissionCheckResult
+ * @property {boolean} isAllowed - `true` if the tool execution is permitted based on the evaluated context, `false` otherwise.
+ * @property {string} [reason] - An optional human-readable string explaining why the permission was
+ * granted or denied. This is useful for logging, debugging, or providing feedback to users/developers.
+ * @property {Record<string, any>} [details] - An optional object for any additional details or metadata
+ * related to the permission decision (e.g., specific capability missing, subscription feature lacking, policy rule invoked).
+ */
+export interface PermissionCheckResult {
+    isAllowed: boolean;
+    reason?: string;
+    details?: Record<string, any>;
+}
+/**
+ * Configuration options for the `ToolPermissionManager`.
+ * This allows administrators to fine-tune how tool permissions are evaluated and enforced.
+ *
+ * @interface ToolPermissionManagerConfig
+ * @property {boolean} [strictCapabilityChecking=true] - If `true` (default), the Persona must possess *all*
+ * capabilities listed in the `tool.requiredCapabilities` array. If `false`, this check might be bypassed
+ * or handled with more leniency (though generally not recommended for tools accessing sensitive resources).
+ * @property {Record<string, FeatureFlag[]>} [toolToSubscriptionFeatures] - Optional. A mapping where keys are
+ * tool IDs (`ITool.id`) or tool names (`ITool.name`), and values are arrays of `FeatureFlag` objects (or their string identifiers).
+ * This allows linking specific tools to subscription features, meaning a user must have the corresponding
+ * features enabled via their subscription tier to use the tool.
+ * @property {boolean} [logToolCalls=false] - If true, detailed information about permission checks for tool calls will be logged. Defaults to false.
+ * @example
+ * // Example: Only users with "AdvancedAnalysisTools" and "PremiumSupport" features can use "financial_data_analyzer_v2"
+ * const config: ToolPermissionManagerConfig = {
+ * strictCapabilityChecking: true,
+ * logToolCalls: true,
+ * toolToSubscriptionFeatures: {
+ * "financial_data_analyzer_v2": [
+ * { flag: "FEATURE_ADVANCED_ANALYSIS", description: "Access to advanced analysis tools" },
+ * { flag: "FEATURE_PREMIUM_SUPPORT_TOOLS", description: "Access to tools included with premium support" }
+ * ]
+ * }
+ * };
+ */
+export interface ToolPermissionManagerConfig {
+    strictCapabilityChecking?: boolean;
+    toolToSubscriptionFeatures?: Record<string, FeatureFlag[]>;
+    logToolCalls?: boolean;
+}
+/**
+ * @interface IToolPermissionManager
+ * @description Defines the contract for a service responsible for managing and enforcing
+ * permissions related to tool execution within the AgentOS ecosystem. Implementations of this
+ * interface will centralize the logic for checking Persona capabilities, user subscription
+ * features, and any other custom authorization rules before a tool is allowed to execute.
+ */
+export interface IToolPermissionManager {
+    /**
+     * Initializes the ToolPermissionManager with its specific configuration and any
+     * necessary service dependencies (like authentication or subscription services).
+     * This method must be called successfully before the manager can process permission checks.
+     *
+     * @public
+     * @async
+     * @param {ToolPermissionManagerConfig} config - The configuration object for the permission manager,
+     * defining its operational parameters and rules.
+     * @param {IAuthService} [authService] - Optional. An instance of the authentication service. This might be used
+     * for more complex permission rules based on user roles, identity verification status, or other authentication attributes.
+     * @param {ISubscriptionService} [subscriptionService] - Optional. An instance of the subscription service. This is
+     * crucial if tool access is tied to user subscription tiers or specific feature flags defined in `ToolPermissionManagerConfig`.
+     * @returns {Promise<void>} A promise that resolves upon successful initialization of the manager.
+     * @throws {GMIError | Error} If initialization fails due to invalid configuration or issues with dependencies.
+     */
+    initialize(config: ToolPermissionManagerConfig, authService?: IAuthService, subscriptionService?: ISubscriptionService): Promise<void>;
+    /**
+     * Checks if the execution of a given tool is permitted based on the comprehensive context provided.
+     * This is the primary method for authorizing tool calls. It should consolidate all relevant checks, including:
+     * - Persona capabilities against `tool.requiredCapabilities`.
+     * - User subscription features against `config.toolToSubscriptionFeatures`.
+     * - Any other custom rules or policies defined within the implementation.
+     *
+     * @public
+     * @async
+     * @param {PermissionCheckContext} context - The context object containing all necessary information
+     * for the permission decision (the tool instance, persona details, user context, etc.).
+     * @returns {Promise<PermissionCheckResult>} A promise that resolves with a `PermissionCheckResult` object,
+     * which includes a boolean `isAllowed` flag and an optional `reason` and `details` for the decision.
+     *
+     * @example
+     * const permissionContext = {
+     * tool: myCalculatorTool,
+     * personaId: "calculator-persona",
+     * personaCapabilities: ["execute_basic_math"],
+     * userContext: { userId: "user-test-123" }
+     * };
+     * const result = await permissionManager.isExecutionAllowed(permissionContext);
+     * if (result.isAllowed) {
+     * console.log("Calculator tool execution permitted.");
+     * } else {
+     * console.warn(`Calculator tool execution denied: ${result.reason}`, result.details);
+     * }
+     */
+    isExecutionAllowed(context: PermissionCheckContext): Promise<PermissionCheckResult>;
+    /**
+     * Performs a specific check to determine if a Persona possesses all the capabilities
+     * explicitly listed as required by a tool.
+     *
+     * @public
+     * @param {string[]} personaCapabilities - An array of capability strings currently held by the Persona.
+     * @param {string[] | undefined} toolRequiredCapabilities - An array of capability strings defined as required by the tool.
+     * If `undefined` or empty, this check inherently passes (tool requires no specific capabilities).
+     * @returns {boolean} `true` if the Persona possesses all capabilities required by the tool, `false` otherwise.
+     */
+    hasRequiredCapabilities(personaCapabilities: string[], toolRequiredCapabilities: string[] | undefined): boolean;
+    /**
+     * Performs a specific check to determine if a user's subscription plan includes the
+     * necessary features or flags that are configured as prerequisites for using a particular tool.
+     * This relies on the `ISubscriptionService` and the `toolToSubscriptionFeatures` mapping
+     * in the `ToolPermissionManagerConfig`.
+     *
+     * @public
+     * @async
+     * @param {string} userId - The ID of the user whose subscription is being checked.
+     * @param {string} toolIdOrName - The unique ID (`ITool.id`) or functional name (`ITool.name`) of the tool.
+     * @returns {Promise<{isAllowed: boolean, missingFeatures?: FeatureFlag[], reason?: string}>}
+     * An object indicating if access is allowed by subscription. If `isAllowed` is `false`,
+     * `missingFeatures` (if applicable) will list the specific subscription features the user lacks,
+     * and `reason` may provide additional context.
+     * @throws {GMIError} If the `ISubscriptionService` is not configured but this check is invoked
+     * for a tool that has required features (`GMIErrorCode.CONFIGURATION_ERROR` or `EXTERNAL_SERVICE_ERROR`).
+     */
+    checkToolSubscriptionAccess(userId: string, toolIdOrName: string): Promise<{
+        isAllowed: boolean;
+        missingFeatures?: FeatureFlag[];
+        reason?: string;
+    }>;
+    /**
+     * Retrieves the list of `FeatureFlag`s that are configured as being required for a specific tool.
+     * This information is sourced from the `toolToSubscriptionFeatures` mapping in the manager's configuration.
+     *
+     * @public
+     * @param {string} toolIdOrName - The ID or name of the tool.
+     * @returns {FeatureFlag[] | undefined} An array of `FeatureFlag` objects required for the tool,
+     * or `undefined` if no specific features are mapped as required for this tool.
+     */
+    getRequiredFeaturesForTool(toolIdOrName: string): FeatureFlag[] | undefined;
+}
+//# sourceMappingURL=IToolPermissionManager.d.ts.map

package/dist/core/tools/permissions/IToolPermissionManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IToolPermissionManager.d.ts","sourceRoot":"","sources":["../../../../src/core/tools/permissions/IToolPermissionManager.ts"],"names":[],"mappings":"AACA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AACjC,OAAO,EAAE,WAAW,EAAE,MAAM,mCAAmC,CAAC;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAE5F;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,KAAK,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,WAAW,EAAE,WAAW,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,2BAA2B;IAC1C,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,0BAA0B,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC;IAC3D,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAGD;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;;;;;;;;;;;;OAeG;IACH,UAAU,CACR,MAAM,EAAE,2BAA2B,EACnC,WAAW,CAAC,EAAE,YAAY,EAC1B,mBAAmB,CAAC,EAAE,oBAAoB,GACzC,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,kBAAkB,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAEpF;;;;;;;;;OASG;IACH,uBAAuB,CACrB,mBAAmB,EAAE,MAAM,EAAE,EAC7B,wBAAwB,EAAE,MAAM,EAAE,GAAG,SAAS,GAC7C,OAAO,CAAC;IAEX;;;;;;;;;;;;;;;;OAgBG;IACH,2BAA2B,CACzB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC;QAAC,SAAS,EAAE,OAAO,CAAC;QAAC,eAAe,CAAC,EAAE,WAAW,EAAE,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAC,CAAC,CAAC;IAEnF;;;;;;;;OAQG;IACH,0BAA0B,CAAC,YAAY,EAAE,MAAM,GAAG,WAAW,EAAE,GAAG,SAAS,CAAC;CAC7E"}

package/dist/core/tools/permissions/IToolPermissionManager.js

@@ -0,0 +1,14 @@
+// File: backend/agentos/core/tools/permissions/IToolPermissionManager.ts
+/**
+ * @fileoverview Defines the IToolPermissionManager interface, responsible for
+ * determining if a tool execution is authorized based on various criteria such as
+ * Persona capabilities, user subscriptions, and potentially other contextual rules.
+ *
+ * @module backend/agentos/core/tools/IToolPermissionManager
+ * @see ./ITool.ts for ITool definition (which includes requiredCapabilities).
+ * @see ../cognitive_substrate/IGMI.ts for UserContext.
+ * @see ../../../../services/user_auth/IAuthService.ts for authentication context.
+ * @see ../../../../services/user_auth/SubscriptionService.ts for subscription and feature flags.
+ */
+export {};
+//# sourceMappingURL=IToolPermissionManager.js.map

package/dist/core/tools/permissions/IToolPermissionManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IToolPermissionManager.js","sourceRoot":"","sources":["../../../../src/core/tools/permissions/IToolPermissionManager.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE;;;;;;;;;;GAUG"}

package/dist/core/tools/permissions/ToolPermissionManager.d.ts

@@ -0,0 +1,203 @@
+/**
+ * @file ToolPermissionManager.ts
+ * @module backend/agentos/core/tools/permissions/ToolPermissionManager
+ * @version 1.2.1
+ *
+ * @description
+ * This module implements the `IToolPermissionManager` interface, providing a robust and
+ * configurable system for managing permissions related to tool execution within the AgentOS ecosystem.
+ * The `ToolPermissionManager` is a critical component for enforcing authorization policies,
+ * evaluating requests against Persona capabilities, user subscription features (via `ISubscriptionService`),
+ * and any other defined contextual rules. Its design emphasizes clarity, extensibility, and
+ * adherence to SOTA TypeScript practices.
+ *
+ * Key Responsibilities:
+ * - Initialization with a detailed configuration (`ToolPermissionManagerConfig`) and essential
+ * dependent services such as `IAuthService` and `ISubscriptionService`.
+ * - Authoritatively checking if a tool execution is permitted based on a comprehensive
+ * `PermissionCheckContext`, which includes the tool in question, the invoking Persona's
+ * profile, and the end-user's context.
+ * - Verifying that the invoking Persona possesses all `requiredCapabilities` specified by the tool,
+ * if `strictCapabilityChecking` is enabled.
+ * - Interacting with the `ISubscriptionService` to determine if the user's current subscription
+ * tier grants access to specific features that may be prerequisites for using certain tools.
+ * - Providing clear, actionable reasons and detailed metadata for all permission decisions,
+ * aiding in debugging, auditing, and user feedback.
+ * - Centralizing tool access logic to enhance security and maintainability across the platform.
+ * - Offering configurable logging for permission checks via `logToolCalls` in its configuration.
+ *
+ * Architectural Tenets Applied:
+ * - Interface-Driven Design: Implements `IToolPermissionManager`.
+ * - Dependency Injection: `IAuthService` and `ISubscriptionService` are injected.
+ * - Comprehensive JSDoc: All public and significant private members are documented.
+ * - Robust Error Handling: Uses standardized `GMIError` and `GMIErrorCode`.
+ * - Configuration Management: Behavior is driven by `ToolPermissionManagerConfig`.
+ * - Strict Type Safety: Leverages TypeScript's type system to prevent common errors.
+ *
+ * @see {@link ./IToolPermissionManager.ts} for the interface definition and related types (including `FeatureFlag` and `ToolPermissionManagerConfig`).
+ * @see {@link ../ITool.ts} for `ITool` and `ToolDefinition` which include `requiredCapabilities`.
+ * @see {@link ../../../cognitive_substrate/IGMI.ts} for `UserContext` definition.
+ * @see {@link ../../../../services/user_auth/SubscriptionService.ts} for `ISubscriptionService` and `ISubscriptionTier`.
+ * @see {@link @framers/agentos/utils/errors.ts} for `GMIError` and `GMIErrorCode`.
+ */
+import { IToolPermissionManager, PermissionCheckContext, PermissionCheckResult, ToolPermissionManagerConfig, FeatureFlag } from './IToolPermissionManager';
+import type { IAuthService, ISubscriptionService } from '../../../services/user_auth/types';
+/**
+ * @class ToolPermissionManager
+ * @implements {IToolPermissionManager}
+ * @description
+ * Manages and enforces permissions for tool usage within the AgentOS ecosystem.
+ * It evaluates tool execution requests against configured policies, Persona capabilities,
+ * and user subscription entitlements to determine authorization. This class provides a
+ * centralized point of control for tool access, enhancing security and feature gating
+ * across the platform.
+ */
+export declare class ToolPermissionManager implements IToolPermissionManager {
+    /**
+     * Readonly configuration for this permission manager instance, applied during initialization.
+     * Defines behavior such as strict capability checking, mappings of tools to subscription features,
+     * and verbosity of logging. Ensures that once initialized, the core operational parameters of
+     * the manager do not change, promoting predictable behavior.
+     * @private
+     * @readonly
+     * @type {Readonly<Required<ToolPermissionManagerConfig>>}
+     */
+    private config;
+    /**
+     * Optional authentication service instance. This service can be used for more complex
+     * permission rules that might depend on user roles, identity verification status,
+     * or other authentication-related attributes not typically found in `UserContext`.
+     * @private
+     * @type {IAuthService | undefined}
+     */
+    private authService?;
+    /**
+     * Optional subscription service instance. This service is crucial if tool access is
+     * gated by user subscription tiers or specific feature flags. It allows the manager
+     * to check if a user's current subscription plan permits the use of a requested tool.
+     * @private
+     * @type {ISubscriptionService | undefined}
+     */
+    private subscriptionService?;
+    /**
+     * Flag indicating if the manager has been successfully initialized.
+     * Operations that depend on configuration or services are blocked until initialization is complete,
+     * ensuring the manager operates in a valid state.
+     * @private
+     * @type {boolean}
+     */
+    private isInitialized;
+    /**
+     * A unique identifier for this `ToolPermissionManager` instance.
+     * Useful for logging, debugging, and potentially differentiating between multiple manager
+     * instances if the system architecture evolves to support such a scenario.
+     * @public
+     * @readonly
+     * @type {string}
+     */
+    readonly managerId: string;
+    /**
+     * Constructs a `ToolPermissionManager` instance.
+     * The instance is not fully operational until the `initialize` method is called
+     * with the necessary configuration and optional service dependencies. This ensures
+     * that the manager always starts in a predictable, uninitialized state.
+     */
+    constructor();
+    /**
+     * Initializes the `ToolPermissionManager` with its configuration and dependent services.
+     * This method must be called and successfully awaited before any permission checks can be performed.
+     * It establishes the manager's operational parameters and links it to essential external services
+     * like authentication and subscription management if they are provided, ensuring all dependencies
+     * are ready for use.
+     *
+     * @public
+     * @async
+     * @param {ToolPermissionManagerConfig} config - The configuration object that defines how
+     * tool permissions are to be evaluated (e.g., strictness of capability checks,
+     * tool-to-feature mappings, logging verbosity). Must not be null or undefined.
+     * @param {IAuthService} [authService] - Optional. An instance of the authentication service,
+     * conforming to the `IAuthService` interface. If provided, it can be used for advanced,
+     * identity-based permission rules not covered by `UserContext` alone.
+     * @param {ISubscriptionService} [subscriptionService] - Optional. An instance of the subscription service,
+     * conforming to the `ISubscriptionService` interface. If provided, it's used to check if a user's
+     * subscription entitles them to use specific tools based on feature flags.
+     * @returns {Promise<void>} A promise that resolves when the manager is fully initialized and ready
+     * to process permission requests.
+     * @throws {GMIError} If the provided `config` is null or undefined, a `GMIError` with
+     * `GMIErrorCode.CONFIGURATION_ERROR` is thrown, preventing initialization with invalid parameters.
+     */
+    initialize(config: ToolPermissionManagerConfig, authService?: IAuthService, subscriptionService?: ISubscriptionService): Promise<void>;
+    /**
+     * Ensures that the permission manager has been properly initialized before attempting
+     * to perform any operations that rely on its configuration or injected services.
+     * This is a critical check to prevent runtime errors due to an unconfigured state.
+     *
+     * @private
+     * @throws {GMIError} If the manager is not initialized, an error with
+     * `GMIErrorCode.NOT_INITIALIZED` is thrown, detailing that an operation was
+     * attempted on an uninitialized manager.
+     */
+    private ensureInitialized;
+    /**
+     * Checks if a Persona possesses all capabilities explicitly required by a tool.
+     * This is a fundamental building block for the overall permission decision in `isExecutionAllowed`.
+     * An empty or undefined `toolRequiredCapabilities` array means the tool has no specific capability prerequisites.
+     *
+     * @public
+     * @param {string[]} personaCapabilities - An array of capability strings (e.g., "filesystem:read", "api:weather")
+     * currently possessed by the Persona. It's expected these are valid, non-empty strings.
+     * @param {string[] | undefined} toolRequiredCapabilities - An array of capability strings defined by the tool
+     * as prerequisites for its execution. If `undefined` or empty, the tool is considered to have no
+     * specific capability requirements, and this check will pass by default.
+     * @returns {boolean} `true` if the Persona possesses all capabilities required by the tool,
+     * or if the tool requires no specific capabilities. Returns `false` if any required capability is missing,
+     * or if the Persona has no capabilities listed when some are required.
+     */
+    hasRequiredCapabilities(personaCapabilities: string[], toolRequiredCapabilities: string[] | undefined): boolean;
+    /**
+     * Retrieves the list of `FeatureFlag`s that are configured as being required for a specific tool.
+     * These feature flags typically map to user subscription tiers or special entitlements.
+     * The information is sourced directly from the `toolToSubscriptionFeatures` mapping
+     * provided in the manager's runtime configuration.
+     *
+     * @public
+     * @param {string} toolIdOrName - The unique ID (`ITool.id`) or functional name (`ITool.name`) of the tool.
+     * The manager will attempt to find a mapping using this identifier. Using `tool.id` is generally preferred
+     * for more stable mappings if tool names might change or be overloaded.
+     * @returns {FeatureFlag[] | undefined} An array of `FeatureFlag` objects (each with a `flag` string
+     * and optional `description`) required for the tool. Returns `undefined` if no specific features
+     * are mapped as required for this tool in the current configuration.
+     */
+    getRequiredFeaturesForTool(toolIdOrName: string): FeatureFlag[] | undefined;
+    /**
+     * Checks if a user's current subscription grants them access to the specific features
+     * required by a particular tool. This method relies on an injected `ISubscriptionService`
+     * to fetch user tier information and validate feature entitlements.
+     *
+     * @public
+     * @async
+     * @param {string} userId - The ID of the user whose subscription entitlements are being verified.
+     * @param {string} toolIdOrName - The unique ID (`ITool.id`) or functional name (`ITool.name`) of the tool.
+     * This identifier is used to look up any feature flag prerequisites from the manager's configuration.
+     * @returns {Promise<{isAllowed: boolean, missingFeatures?: FeatureFlag[], reason?: string}>}
+     * An object detailing the outcome of the subscription check.
+     * @throws {GMIError} If critical services are misconfigured or if interaction with `ISubscriptionService` fails.
+     */
+    checkToolSubscriptionAccess(userId: string, toolIdOrName: string): Promise<{
+        isAllowed: boolean;
+        missingFeatures?: FeatureFlag[];
+        reason?: string;
+    }>;
+    /**
+     * Determines if a tool execution is permitted based on the comprehensive provided context.
+     * This is the primary method for authorizing tool calls.
+     *
+     * @public
+     * @async
+     * @param {PermissionCheckContext} context - The context for the permission check.
+     * @returns {Promise<PermissionCheckResult>} A promise resolving to a `PermissionCheckResult`.
+     * @throws {GMIError} If the manager is not initialized or if an unrecoverable error occurs.
+     */
+    isExecutionAllowed(context: PermissionCheckContext): Promise<PermissionCheckResult>;
+}
+//# sourceMappingURL=ToolPermissionManager.d.ts.map

package/dist/core/tools/permissions/ToolPermissionManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolPermissionManager.d.ts","sourceRoot":"","sources":["../../../../src/core/tools/permissions/ToolPermissionManager.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,qBAAqB,EACrB,2BAA2B,EAC3B,WAAW,EACZ,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,YAAY,EAAE,oBAAoB,EAAqB,MAAM,mCAAmC,CAAC;AAI/G;;;;;;;;;GASG;AACH,qBAAa,qBAAsB,YAAW,sBAAsB;IAClE;;;;;;;;OAQG;IACH,OAAO,CAAC,MAAM,CAAmD;IAEjE;;;;;;OAMG;IACH,OAAO,CAAC,WAAW,CAAC,CAAe;IAEnC;;;;;;OAMG;IACH,OAAO,CAAC,mBAAmB,CAAC,CAAuB;IAEnD;;;;;;OAMG;IACH,OAAO,CAAC,aAAa,CAAkB;IAEvC;;;;;;;OAOG;IACH,SAAgB,SAAS,EAAE,MAAM,CAAC;IAElC;;;;;OAKG;;IAKH;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACU,UAAU,CACrB,MAAM,EAAE,2BAA2B,EACnC,WAAW,CAAC,EAAE,YAAY,EAC1B,mBAAmB,CAAC,EAAE,oBAAoB,GACzC,OAAO,CAAC,IAAI,CAAC;IA+BhB;;;;;;;;;OASG;IACH,OAAO,CAAC,iBAAiB;IAUzB;;;;;;;;;;;;;;OAcG;IACI,uBAAuB,CAC5B,mBAAmB,EAAE,MAAM,EAAE,EAC7B,wBAAwB,EAAE,MAAM,EAAE,GAAG,SAAS,GAC7C,OAAO;IAqBV;;;;;;;;;;;;;OAaG;IACI,0BAA0B,CAAC,YAAY,EAAE,MAAM,GAAG,WAAW,EAAE,GAAG,SAAS;IAKlF;;;;;;;;;;;;;OAaG;IACU,2BAA2B,CACtC,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC;QAAC,SAAS,EAAE,OAAO,CAAC;QAAC,eAAe,CAAC,EAAE,WAAW,EAAE,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAC,CAAC;IAsDlF;;;;;;;;;OASG;IACU,kBAAkB,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,qBAAqB,CAAC;CAuDjG"}