/*************************************************************************
 * Copyright 2025 Adobe
 * All Rights Reserved.
 *
 * NOTICE: Adobe permits you to use, modify, and distribute this file in
 * accordance with the terms of the Adobe license agreement accompanying
 * it. If you have received this file from a source other than Adobe,
 * then your use, modification, or distribution of it requires the prior
 * written permission of Adobe.
 **************************************************************************/
/** Property definition within a JSON Schema. */
export interface JSONSchemaProperty {
    type: string;
    description?: string;
    enum?: string[];
    items?: JSONSchemaProperty;
    properties?: Record<string, JSONSchemaProperty>;
    required?: string[];
}
/** JSON Schema for a tool's input parameters. */
export interface JSONSchema {
    type: 'object';
    properties?: Record<string, JSONSchemaProperty>;
    required?: string[];
}
/**
 * Describes a tool that AO2's LLM can invoke. Sent as A2A metadata
 * alongside each user message. The LLM uses `description` and
 * `inputSchema` to decide when and how to call the tool.
 *
 * This must remain fully serializable — it crosses postMessage.
 */
export interface ToolDefinition {
    /** Unique tool name. Must be globally unique across all SPAs. */
    name: string;
    /** Human-readable description. The LLM uses this to decide when to call the tool. */
    description: string;
    /** JSON Schema describing the tool's input parameters. */
    inputSchema: JSONSchema;
    /** Function that executes the tool. */
    execute?: (args: Record<string, any>) => Promise<any>;
    samples?: Record<string, any>[];
    source?: string;
}
/**
 * Function that executes a tool call locally in the APP iframe.
 * This is stored in module-runtime's handler registry and is NEVER
 * sent across postMessage.
 */
export type ToolHandler = (args: Record<string, any>) => Promise<any>;
/**
 * OpenAI-style function tool definition.
 * This is the format that agent-platform (AO) expects for client tool
 * bridge integration. Each tool is wrapped as `{ type: 'function', function: {...} }`.
 */
export interface ClientToolDefinition {
    type: 'function';
    function: {
        name: string;
        description: string;
        parameters: JSONSchema;
    };
}
/**
 * Convenience type for registering a tool with both its definition
 * and handler together.
 */
export interface ToolRegistration {
    definition: ToolDefinition;
    handler: ToolHandler;
}
/**
 * Solution-facing API for registering browser-side tools
 * that AO2 can invoke via the WebMCP protocol.
 */
export interface MCPApi {
    /**
     * Execute a registered tool by name.
     *
     * If the tool is registered in the current frame, its handler is
     * called directly with no postMessage overhead. Otherwise the call
     * is routed through Core to whichever frame owns the tool.
     *
     * When `targetFrameId` is provided, the call targets the specific
     * frame's version of the tool. If that frame matches the current
     * frame, execution is still local. Otherwise Core routes the call
     * to the specified frame.
     *
     * ***Example:***
     *
     * ```typescript
     * // Execute in any frame that has the tool
     * const result = await mcp.executeTool('lookupUI', { type: 'button' });
     *
     * // Target a specific frame's version
     * const result = await mcp.executeTool('lookupUI', { type: 'button' }, 'myAppId');
     * ```
     *
     * @param name - The tool name to execute
     * @param args - Arguments to pass to the tool handler
     * @param targetFrameId - Optional frame ID to target a specific frame's tool
     * @returns The tool handler's return value
     */
    executeTool: (name: string, args?: Record<string, any>, targetFrameId?: string) => Promise<any>;
    /**
     * Get the tools registered in the current frame.
     *
     * Returns an array of tool definitions in OpenAI function-calling format.
     *
     * ***Example:***
     *
     * ```typescript
     * const tools = mcp.getTools();
     * // [{ type: 'function', function: { name: 'lookupUI', description: '...', parameters: {...} } }, ...]
     * console.log(tools);
     * ```
     *
     * @returns An array of client tool definitions
     */
    getTools: () => ClientToolDefinition[];
    /**
     * Register a tool with both its definition and handler.
     *
     * The definition (serializable) is sent to Core so it appears
     * in the A2A metadata sent to AO2 with each user message.
     * The handler (a function) stays local in the APP iframe and
     * is called when AO2 invokes the tool.
     *
     * ***Example:***
     *
     * ```typescript
     * mcp.registerTool(
     *   {
     *     name: 'getPageInfo',
     *     description: 'Returns information about the current page',
     *     inputSchema: { type: 'object', properties: {} }
     *   },
     *   async () => ({ title: document.title, url: window.location.href })
     * );
     * ```
     *
     * @param definition - Serializable tool definition (name, description, inputSchema)
     * @param handler - Async function that executes the tool locally
     */
    registerTool: (definition: ToolDefinition, handler: ToolHandler) => void;
    /**
     * Remove a previously registered tool.
     *
     * Removes the handler locally and notifies Core to remove
     * the definition from the A2A metadata.
     *
     * ***Example:***
     *
     * ```typescript
     * mcp.unregisterTool('getPageInfo');
     * ```
     *
     * @param name - The tool name to unregister
     */
    unregisterTool: (name: string) => void;
}
declare const mcp: MCPApi;
export default mcp;