/**
 * MCP tool registry — framework for `tools/list` and `tools/call` per MCP
 * §server/tools. No real tools register here yet — the operations profile
 * walks `OPERATION_FUNCTION_MAP`, and the application profile walks the
 * `Resources` registry. Both call `addTool(def)` to publish.
 *
 * Filtering follows a two-step pattern:
 *   1. Class-level verb introspection (which tools are *publishable*)
 *      reuses the prototype-comparison helper from `resources/openApi.ts:149-153`.
 *   2. User-level RBAC walk (which publishable tools are *visible*) reuses
 *      the direct `user.role.permission[db].tables[table]` walk from
 *      `dataLayer/schemaDescribe.ts:29-49`. Resource.allow* methods are
 *      *not* used — they're per-record instance methods.
 *
 * Security model — important:
 *   - `visibleTo` controls **listing** (the LLM only sees what it's likely
 *     allowed to use). It is **not** invoked at `tools/call` time and is
 *     explicitly NOT a security boundary.
 *   - **Enforcement runs in the tool handler at call time**, via Harper's
 *     existing `transactional()` + per-record `allow{Read,Create,Update,
 *     Delete}` predicates. The framework intentionally passes a
 *     known-but-filtered-out tool through to its handler so an LLM that
 *     hallucinates a name gets a clean `isError` result from the runtime
 *     predicate. See the `tools/call` pass-through test in
 *     `transport.test.js`.
 */
import type { McpProfile } from './transport.ts';
export interface ToolAnnotations {
    title?: string;
    readOnlyHint?: boolean;
    destructiveHint?: boolean;
    idempotentHint?: boolean;
    openWorldHint?: boolean;
}
export interface ToolContent {
    type: 'text' | 'image' | 'audio' | 'resource';
    text?: string;
    data?: string;
    mimeType?: string;
}
export interface ToolResult {
    content: ToolContent[];
    isError?: boolean;
    structuredContent?: unknown;
}
/** Public shape sent to clients on `tools/list`. */
export interface ToolDescriptor {
    name: string;
    description: string;
    inputSchema: object;
    outputSchema?: object;
    annotations?: ToolAnnotations;
}
/** Authenticated user object as Harper builds it (subset we touch). */
export interface AuthedUser {
    username?: string;
    role?: {
        role?: string;
        permission?: {
            super_user?: boolean;
            structure_user?: boolean;
            operations?: string[];
            [database: string]: boolean | string[] | undefined | {
                describe?: boolean;
                tables?: {
                    [table: string]: undefined | {
                        read?: boolean;
                        insert?: boolean;
                        update?: boolean;
                        delete?: boolean;
                        describe?: boolean;
                        attribute_permissions?: unknown;
                    };
                };
            };
        };
    };
}
export interface ToolCallContext {
    user: AuthedUser;
    profile: McpProfile;
    sessionId: string;
}
/**
 * Internal tool definition. `handler` and `visibleTo` are not sent to the
 * client; only the public `ToolDescriptor` fields are.
 */
export interface ToolDef extends ToolDescriptor {
    profile: McpProfile;
    visibleTo: (user: AuthedUser) => boolean;
    handler: (args: unknown, context: ToolCallContext) => Promise<ToolResult> | ToolResult;
}
export declare function addTool(def: ToolDef): void;
export declare function removeTool(name: string): boolean;
export declare function getTool(name: string): ToolDef | undefined;
/**
 * Drop the pagination cache entry for a session. Called by
 * `session.deleteSession` so the cache doesn't outlive the session that
 * created it. Without this, every session that ever paged tools/list
 * leaves an orphan entry until the process restarts.
 */
export declare function clearSessionCache(sessionId: string): void;
/** Test seam: drop all registrations. */
export declare function _resetRegistryForTest(): void;
export interface ListToolsArgs {
    user: AuthedUser;
    profile: McpProfile;
    sessionId: string;
    cursor?: string;
    limit: number;
}
export interface ListToolsResult {
    tools: ToolDescriptor[];
    nextCursor?: string;
}
/**
 * Filter the registry to tools the user can see on this profile, then page.
 *
 * Cursor encoding: base64 of `{offset:N}`. Opaque to clients per MCP
 * §server/utilities/pagination. A fresh call (no cursor) recomputes and
 * caches the filtered list; subsequent paged calls reuse the cache so
 * pagination is stable even if the registry mutates between pages.
 */
export declare function listTools(args: ListToolsArgs): ListToolsResult;
/** True if any role-level flag grants super-user privilege. */
export declare function isSuperUser(user: AuthedUser | undefined): boolean;
/**
 * Class-level verb introspection. Mirrors `resources/openApi.ts:149-153` so
 * a class is considered to "have" a verb only if its prototype overrides the
 * base Resource implementation. Note that `post`'s default in Harper's
 * `Resource` is a no-op that ResourceClass implementations frequently
 * override implicitly via `update` — the openApi pattern accounts for that.
 */
export declare function hasClassLevelVerbs(prototype: any, resourcePrototype: any): {
    get: boolean;
    post: boolean;
    put: boolean;
    patch: boolean;
    delete: boolean;
};
/**
 * Role-level operations check for the operations profile. Returns true if
 * the user has the role-level privilege required to invoke `operation`,
 * regardless of any per-call schema/table predicate (those run at tool-call
 * time).
 *
 * The implementation here is intentionally conservative — only flags that
 * grant operations globally short-circuit. Per-operation per-target checks
 * are evaluated at call time by Harper's existing `verifyPerms`.
 */
export declare function canRoleInvokeOperation(user: AuthedUser, operation: string): boolean;
