@microsoft/app-manifest 1.0.4-alpha.30ed24296.0 → 1.0.4-alpha.3344620f2.0

package/build/generated-types/copilot/plugin/ApiPluginManifestV2D4.d.ts

@@ -0,0 +1,527 @@
+/**
+ * The root of the plugin manifest document is a JSON object that contains members that
+ * describe the plugin.
+ */
+export interface APIPluginManifestV2D4 {
+    /**
+     * The schema version. Previous versions are `v1`, `v2`, `v2.1`, `v2.2`, and `v2.3`.
+     */
+    schema_version: "v2.4";
+    /**
+     * A short, human-readable name for the plugin. It MUST contain at least one nonwhitespace
+     * character. Characters beyond 20 MAY be ignored. This property is localizable.
+     */
+    name_for_human: string;
+    /**
+     * An identifier used to prevent name conflicts between function names from different
+     * plugins that are used within the same execution context. The value MUST match the regex
+     * ^[A-Za-z0-9-]+ as defined by [RFC9485]. This is a required member.
+     */
+    namespace: string;
+    /**
+     * The description for the plugin that is provided to the model. This description should
+     * describe what the plugin is for, and in what circumstances its functions are relevant.
+     * Characters beyond 2048 MAY be ignored. This property is localizable.
+     */
+    description_for_model?: string;
+    /**
+     * A human-readable description of the plugin. Characters beyond 100 MAY be ignored. This
+     * property is localizable.
+     */
+    description_for_human: string;
+    /**
+     * A URL used to fetch a logo that MAY be used by the orchestrator. Implementations MAY
+     * provide alternative methods to provide logos that meet their visual requirements. This
+     * property is localizable.
+     */
+    logo_url?: any;
+    /**
+     * An email address of a contact for safety/moderation, support, and deactivation.
+     */
+    contact_email?: string;
+    /**
+     * An absolute URL that locates a document containing the terms of service for the plugin.
+     * This property is localizable.
+     */
+    legal_info_url?: any;
+    /**
+     * An absolute URL that locates a document containing the privacy policy for the plugin.
+     * This property is localizable.
+     */
+    privacy_policy_url?: any;
+    /**
+     * A set of function objects describing the functions available to the plugin. Each function
+     * object name MUST be unique within the array. The order of the array isn't significant. If
+     * the `functions` property isn't present and there's an OpenAPI runtime, the functions are
+     * inferred from the OpenAPI operations.
+     */
+    functions?: FunctionObject[];
+    /**
+     * A list of runtime configurations that determine how functions are invoked.
+     */
+    runtimes?: APIPluginManifestV2D[];
+    /**
+     * Describes capabilities of the plugin.
+     */
+    capabilities?: PluginCapabilitiesObject;
+    [property: string]: any;
+}
+/**
+ * Describes capabilities of the plugin.
+ */
+export interface PluginCapabilitiesObject {
+    /**
+     * Conversation starters that can be displayed to the user for suggestions on how to invoke
+     * the plugin.
+     */
+    conversation_starters?: ConversationStarterObject[];
+    [property: string]: any;
+}
+/**
+ * An example of a question that the plugin can answer.
+ */
+export interface ConversationStarterObject {
+    /**
+     * The text of the conversation starter. This property is localizable.
+     */
+    text: string;
+    /**
+     * The title of the conversation starter. This property is localizable.
+     */
+    title?: string;
+    [property: string]: any;
+}
+/**
+ * Information related to how the model should interact with a function.
+ */
+export interface FunctionObject {
+    id?: string;
+    /**
+     * A string that uniquely identifies this function. Runtime objects MAY reference this
+     * identifier to bind the runtime to the function. When the function is bound to an OpenAPI
+     * runtime, the value must match an `operationId` value in the OpenAPI description.
+     */
+    name: string;
+    /**
+     * A description better tailored to the model, such as token context length considerations
+     * or keyword usage for improved plugin prompting.
+     */
+    description?: string;
+    /**
+     * An object that contains members that describe the parameters of a function in a runtime
+     * agnostic way. It mirrors the shape of [json-schema][] but only supports a small subset of
+     * the JSON schema capabilities. If the `parameters` property isn't present, functions
+     * described by a runtime object of type `OpenApi` use the OpenAPI description to determine
+     * the parameters. Each member in the JSON object is a function parameter object that
+     * describes the semantics of the parameter.
+     */
+    parameters?: FunctionParametersObject;
+    /**
+     * Describes the semantics of the value returned from the function.
+     */
+    returns?: ReturnObject;
+    /**
+     * Defines state objects for orchestrator states.
+     */
+    states?: FunctionStatesObject;
+    /**
+     * Contains a collection of data used to configure optional capabilities of the orchestrator
+     * while invoking the function.
+     */
+    capabilities?: FunctionCapabilitiesObject;
+    [property: string]: any;
+}
+/**
+ * Contains a collection of data used to configure optional capabilities of the orchestrator
+ * while invoking the function.
+ */
+export interface FunctionCapabilitiesObject {
+    /**
+     * Describes a confirmation dialog that SHOULD be presented to the user before invoking the
+     * function.
+     */
+    confirmation?: ConfirmationObject;
+    /**
+     * Describes how the orchestrator can interpret the response payload and provide a visual
+     * rendering.
+     */
+    response_semantics?: ResponseSemanticsObject;
+    /**
+     * Describes the security information to be used to aid in determining the relative risk of
+     * invoking the function.
+     */
+    security_info?: SecurityInfoObject;
+    [property: string]: any;
+}
+/**
+ * Describes a confirmation dialog that SHOULD be presented to the user before invoking the
+ * function.
+ *
+ * Describes how the orchestrator asks the user to confirm before calling a function.
+ */
+export interface ConfirmationObject {
+    /**
+     * Specifies the type of confirmation.
+     */
+    type?: ConfirmationType;
+    /**
+     * The title of the confirmation dialog. This property is localizable.
+     */
+    title?: string;
+    /**
+     * The text of the confirmation dialog. This property is localizable.
+     */
+    body?: string;
+    /**
+     * Indicates the function is non-consequential. If true users may choose Always Allow.
+     * Default false. For OpenAPI GET only and ignored if x-oai-isConsequential is present or
+     * method != GET.
+     */
+    isNonConsequential?: boolean;
+    [property: string]: any;
+}
+/**
+ * Specifies the type of confirmation.
+ */
+export type ConfirmationType = "None" | "AdaptiveCard";
+/**
+ * Describes how the orchestrator can interpret the response payload and provide a visual
+ * rendering.
+ *
+ * Contains information to identify semantics of response payload and enable rendering that
+ * information in a rich visual experience using [adaptive cards](https://adaptivecards.io/).
+ */
+export interface ResponseSemanticsObject {
+    /**
+     * A JSONPath [RFC9535][] query that identifies a set of elements from the function response
+     * to be rendered using the template specified in each item.
+     */
+    data_path: string;
+    /**
+     * Allows mapping of JSONPath queries to well-known data elements. Each JSONPath query is
+     * relative to a result value.
+     */
+    properties?: ResponseSemanticsPropertiesObject;
+    /**
+     * A JSON object that either: conforms with the [Adaptive Card
+     * Schema](https://adaptivecards.io/schemas/adaptive-card.json) and templating language, or
+     * contains a `file` property that references a file containing the Adaptive Card Schema.
+     * This Adaptive Card instance is used to render a result from the plugin response. This
+     * value is used if the `template_selector` isn't present or fails to resolve to an adaptive
+     * card. If using the file reference option, the value of `file` MUST be a relative path to
+     * a JSON file containing a valid Adaptive Card Schema. The path is relative to the location
+     * of the manifest document.
+     */
+    static_template?: StaticTemplate;
+    /**
+     * A JSON string containing a JSONPath query that when applied to the response payload will
+     * return an [Adaptive Card
+     * Template](https://learn.microsoft.com/adaptive-cards/templating/language) that will be
+     * used to authenticate the user.
+     */
+    oauth_card_path?: string;
+    [property: string]: any;
+}
+/**
+ * Allows mapping of JSONPath queries to well-known data elements. Each JSONPath query is
+ * relative to a result value.
+ */
+export interface ResponseSemanticsPropertiesObject {
+    /**
+     * Title of a citation for the result.
+     */
+    title?: string;
+    /**
+     * Subtitle of a citation for the result.
+     */
+    subtitle?: string;
+    /**
+     * URL of a citation for the result.
+     */
+    url?: string;
+    /**
+     * URL of a thumbnail image for the result.
+     */
+    thumbnail_url?: string;
+    /**
+     * Data sensitivity indicator of the result contents.
+     */
+    information_protection_label?: string;
+    /**
+     * A JSONPath query that returns an [Adaptive Card
+     * Template](https://learn.microsoft.com/adaptive-cards/templating/language) from the API
+     * response to be used for rendering the result.
+     */
+    template_selector?: string;
+    [property: string]: any;
+}
+/**
+ * A JSON object that either: conforms with the [Adaptive Card
+ * Schema](https://adaptivecards.io/schemas/adaptive-card.json) and templating language, or
+ * contains a `file` property that references a file containing the Adaptive Card Schema.
+ * This Adaptive Card instance is used to render a result from the plugin response. This
+ * value is used if the `template_selector` isn't present or fails to resolve to an adaptive
+ * card. If using the file reference option, the value of `file` MUST be a relative path to
+ * a JSON file containing a valid Adaptive Card Schema. The path is relative to the location
+ * of the manifest document.
+ *
+ * An inline Adaptive Card definition that conforms with the Adaptive Card Schema and
+ * templating language.
+ *
+ * A file reference to an Adaptive Card definition. The file property MUST contain a
+ * relative path to a JSON file containing a valid Adaptive Card Schema.
+ */
+export interface StaticTemplate {
+    /**
+     * A relative path to a JSON file containing a valid Adaptive Card Schema. The path is
+     * relative to the location of the manifest document.
+     */
+    file?: string;
+    [property: string]: any;
+}
+/**
+ * Describes the security information to be used to aid in determining the relative risk of
+ * invoking the function.
+ */
+export interface SecurityInfoObject {
+    /**
+     * An array of strings that describe the data handling behavior of the plugin.
+     */
+    data_handling?: DataHandling[];
+    [property: string]: any;
+}
+export type DataHandling = "GetPublicData" | "GetPrivateData" | "DataTransform" | "ResourceStateUpdate";
+/**
+ * An object that contains members that describe the parameters of a function in a runtime
+ * agnostic way. It mirrors the shape of [json-schema][] but only supports a small subset of
+ * the JSON schema capabilities. If the `parameters` property isn't present, functions
+ * described by a runtime object of type `OpenApi` use the OpenAPI description to determine
+ * the parameters. Each member in the JSON object is a function parameter object that
+ * describes the semantics of the parameter.
+ *
+ * An object that is used to identify the set of parameters that can be passed to the
+ * function. This object is structured to mirror the shape of a JSON Schema object but it
+ * only supports a subset of JSON Schema keywords.
+ */
+export interface FunctionParametersObject {
+    /**
+     * The JSON Schema type.
+     */
+    type?: "object";
+    /**
+     * An object that maps parameter names to their definitions.
+     */
+    properties: {
+        [key: string]: any;
+    };
+    /**
+     * The names of properties that are required parameters. Unlike in JSON Schema, the values
+     * in this array MUST match the names listed in the `properties` property.
+     */
+    required?: string[];
+    [property: string]: any;
+}
+/**
+ * Describes the semantics of the value returned from the function.
+ *
+ * Contains the semantics of the value returned from the function.
+ *
+ * Indicates that the function returns a response that is compatible with the Rich Responses
+ * protocol.
+ */
+export interface ReturnObject {
+    /**
+     * Specifies the type of the value returned by the API.
+     */
+    type?: "string";
+    /**
+     * A description of the value returned by the API.
+     */
+    description?: string;
+    $ref?: "https://copilot.microsoft.com/schemas/rich-response-v1.0.json";
+    [property: string]: any;
+}
+/**
+ * Specifies the type of the value returned by the API.
+ */
+/**
+ * Defines state objects for orchestrator states.
+ */
+export interface FunctionStatesObject {
+    /**
+     * The state in which the model can call functions and do computations.
+     */
+    reasoning?: StateObject;
+    /**
+     * The state in which the model can generate text that is shown to the user. The model can't
+     * invoke functions in the responding state.
+     */
+    responding?: StateObject;
+    [property: string]: any;
+}
+/**
+ * The state in which the model can call functions and do computations.
+ *
+ * Contains specific instructions for when a function is invoked in a specific orchestrator
+ * state.
+ *
+ * The state in which the model can generate text that is shown to the user. The model can't
+ * invoke functions in the responding state.
+ */
+export interface StateObject {
+    /**
+     * Describes the purpose of a function when used in a specific orchestrator state.
+     */
+    description?: string;
+    /**
+     * A string or an array of strings that are used to provide instructions to the orchestrator
+     * on how to use this function while in a specific orchestrator state. Providing a single
+     * string indicates the intent to provide a complete set of instructions that would override
+     * any built-in function prompts. Providing an array of strings indicates the intent to
+     * augment the built-in function prompting mechanism.
+     */
+    instructions?: string[] | string;
+    /**
+     * A string or an array of strings that are used to provide examples to the orchestrator on
+     * how this function can be invoked.
+     */
+    examples?: string[] | string;
+    [property: string]: any;
+}
+/**
+ * Defines how a specific runtime invokes functions, including auth and spec details.
+ */
+export interface APIPluginManifestV2D {
+    /**
+     * The type of runtime. Must be 'OpenApi', 'LocalPlugin', or 'RemoteMCPServer'.
+     */
+    type: RuntimeType;
+    auth: RuntimeAuthenticationObject;
+    /**
+     * The names of the functions that are available in this runtime. A single wildcard ("*")
+     * value can be provided to enable all functions in the OpenAPI description. More than one
+     * runtime MUST NOT declare support for the same function either implicitly or explicitly.
+     */
+    run_for_functions?: string[];
+    /**
+     * Runtime-specific configuration object.
+     */
+    spec: Spec;
+    /**
+     * A Liquid template used to transform the plugin response payload.
+     */
+    output_template?: string;
+}
+/**
+ * Contains information used by the plugin to authenticate to the runtime.
+ */
+export interface RuntimeAuthenticationObject {
+    /**
+     * Specifies the type of authentication required to invoke a function.
+     */
+    type: TypeEnum;
+    /**
+     * Specifies the type of authentication required to invoke a function.
+     */
+    Type?: TypeEnum;
+    /**
+     * A value used when `type` is `OAuthPluginVault` or `ApiKeyPluginVault`. The `reference_id`
+     * value is acquired independently when providing the necessary authentication configuration
+     * values. This mechanism exists to prevent the need for storing secret values in the plugin
+     * manifest.
+     */
+    reference_id?: string;
+}
+/**
+ * Specifies the type of authentication required to invoke a function.
+ */
+export type TypeEnum = "None" | "OAuthPluginVault" | "ApiKeyPluginVault";
+/**
+ * Runtime-specific configuration object.
+ *
+ * Configuration for invoking an OpenAPI-based runtime.
+ *
+ * Configuration for invoking a local plugin runtime.
+ *
+ * Configuration for invoking a remote MCP server runtime.
+ */
+export interface Spec {
+    /**
+     * The URL to the OpenAPI specification (ignored if api_description is present).
+     *
+     * A JSON string that represents the URL of the MCP server. This URL MUST be a valid
+     * absolute URL. This member is required when the type is RemoteMCPServer.
+     */
+    url?: string;
+    /**
+     * A string that contains an OpenAPI description. If this member is present, `url` isn't
+     * required and is ignored if present.
+     */
+    api_description?: string;
+    /**
+     * A JSON string that contains the progress style that will be used to display the progress
+     * of the function. The value MUST be one of the following values: None, ShowUsage,
+     * ShowUsageWithInput, ShowUsageWithInputAndOutput.
+     */
+    progress_style?: ProgressStyle;
+    /**
+     * A JSON string that represents a local runtime identifier that links to a specific
+     * function to invoke locally (e.g. in the case of Windows it will link to a particular
+     * app). In the case of an Office Addin that is implementing the function, the value MUST be
+     * the string Microsoft.Office.Addin.
+     */
+    local_endpoint?: "Microsoft.Office.Addin";
+    /**
+     * An optional JSON array of enumerated strings that can take values as mail, workbook,
+     * document or presentation. The value represent the host apps this LocalPlugin can run-in.
+     */
+    allowed_host?: AllowedHost[];
+    /**
+     * A JSON object that contains either a reference to an external MCP tool description file
+     * or inline tool definitions. When present, this indicates that static tool definitions
+     * should be used instead of dynamic discovery. When absent, the runtime MUST use dynamic
+     * tool discovery by calling the MCP server's tools/list method.
+     */
+    mcp_tool_description?: MCPTool;
+}
+export type AllowedHost = "mail" | "workbook" | "document" | "presentation";
+/**
+ * A JSON string that represents a local runtime identifier that links to a specific
+ * function to invoke locally (e.g. in the case of Windows it will link to a particular
+ * app). In the case of an Office Addin that is implementing the function, the value MUST be
+ * the string Microsoft.Office.Addin.
+ */
+/**
+ * A JSON object that contains either a reference to an external MCP tool description file
+ * or inline tool definitions. When present, this indicates that static tool definitions
+ * should be used instead of dynamic discovery. When absent, the runtime MUST use dynamic
+ * tool discovery by calling the MCP server's tools/list method.
+ *
+ * A reference to an external MCP tool description file.
+ *
+ * Inline tool definitions matching the format returned by the MCP server's tools/list
+ * method.
+ */
+export interface MCPTool {
+    /**
+     * A string that identifies the relative path to the MCP tool description file within the
+     * app package. The file MUST be a valid JSON file that contains tool descriptions matching
+     * the format returned by the MCP server's tools/list method.
+     */
+    file?: string;
+    [property: string]: any;
+}
+/**
+ * A JSON string that contains the progress style that will be used to display the progress
+ * of the function. The value MUST be one of the following values: None, ShowUsage,
+ * ShowUsageWithInput, ShowUsageWithInputAndOutput.
+ */
+export type ProgressStyle = "None" | "ShowUsage" | "ShowUsageWithInput" | "ShowUsageWithInputAndOutput";
+/**
+ * The type of runtime. Must be 'OpenApi', 'LocalPlugin', or 'RemoteMCPServer'.
+ */
+export type RuntimeType = "OpenApi" | "LocalPlugin" | "RemoteMCPServer";
+export declare class Convert {
+    static toAPIPluginManifestV2D4(json: string): APIPluginManifestV2D4;
+    static aPIPluginManifestV2D4ToJson(value: APIPluginManifestV2D4): string;
+}