@dollhousemcp/mcp-server/dist/handlers/mcp-aql/policies/AgentToolPolicyTranslator.d.ts

DollhouseMCP - A Model Context Protocol (MCP) server that enables dynamic AI persona management from markdown files, allowing Claude and other compatible AI assistants to activate and switch between different behavioral personas.

/**
 * Agent Tool Policy Translator (Issue #449)
 *
 * Translates an agent's `tools` configuration (allowed/denied endpoint names)
 * into an `ElementGatekeeperPolicy` that the Gatekeeper can enforce.
 *
 * This bridges the informational `AgentToolConfig` with the enforceable
 * Gatekeeper policy system, giving agent tool restrictions programmatic teeth.
 *
 * **Policy precedence:** This translator is only used when an agent has no
 * explicit `gatekeeper` policy. If both `gatekeeper` and `tools` are present,
 * the explicit `gatekeeper` policy takes precedence (see MCPAQLHandler).
 *
 * @module AgentToolPolicyTranslator
 */
import type { ElementGatekeeperPolicy } from '../GatekeeperTypes.js';
import type { AgentToolConfig } from '../../../elements/agents/types.js';
/**
 * Translates an {@link AgentToolConfig} into an {@link ElementGatekeeperPolicy}.
 *
 * The translation works as follows:
 * - If `tools.allowed` is specified, all operations **not** in the allowed
 *   endpoints are added to the deny list (allowlist → denylist inversion).
 * - If `tools.denied` is specified, all operations from the denied endpoints
 *   are added to the deny list directly.
 * - Both `allowed` and `denied` can be specified simultaneously; their effects
 *   are cumulative (union of denied operations).
 *
 * Lifecycle and safety operations ({@link EXEMPT_OPERATIONS}) are **never**
 * included in the synthesized deny list, regardless of the tool config.
 *
 * @param toolConfig - The agent's tool configuration containing allowed/denied endpoint names
 * @returns A synthesized {@link ElementGatekeeperPolicy} with a deny list,
 *          or `undefined` if the config produces no restrictions
 *
 * @example
 * ```typescript
 * // Agent that can only read — all other endpoints denied
 * translateToolConfigToPolicy({ allowed: ['mcp_aql_read'] });
 * // → { deny: ['addEntry', 'clear', 'create_element', 'delete_element', 'edit_element', ...] }
 *
 * // Agent that cannot delete — only delete operations denied
 * translateToolConfigToPolicy({ allowed: ['mcp_aql_create', 'mcp_aql_read', 'mcp_aql_update', 'mcp_aql_execute'] });
 * // → { deny: ['clear', 'delete_element'] }
 *
 * // No restrictions — returns undefined
 * translateToolConfigToPolicy({ allowed: ['mcp_aql_create', 'mcp_aql_read', 'mcp_aql_update', 'mcp_aql_delete', 'mcp_aql_execute'] });
 * // → undefined
 * ```
 */
export declare function translateToolConfigToPolicy(toolConfig: AgentToolConfig): ElementGatekeeperPolicy | undefined;
//# sourceMappingURL=AgentToolPolicyTranslator.d.ts.map