import type { ConnectionAuthDefinition, HeadersDefinition, ToolFilterDefinition } from "#runtime/connections/types.js";
import type { NeedsApprovalContext } from "#public/definitions/tool.js";
/**
 * The OpenAPI document backing the connection: either an HTTPS URL the
 * runtime fetches on first use, or an already-parsed OpenAPI 3.x /
 * Swagger 2.0 object.
 */
export type OpenAPISpecSource = string | Record<string, unknown>;
/**
 * Public definition for an OpenAPI connection authored in
 * `connections/*.ts`.
 *
 * The connection's runtime name is derived from its filename (the slug
 * under `agent/connections/`, without the extension). A connection
 * authored at `agent/connections/vercel.ts` is registered as
 * `"vercel"`.
 *
 * Each operation in the document becomes a connection tool the model can
 * discover via `connection_search` and call by its qualified name (e.g.
 * `vercel__getProjects`). The tool name is the operation's
 * `operationId`; operations without one get a deterministic synthesized
 * name (`<method>_<sanitized-path>`).
 *
 * Both `auth` and `headers` are optional. Omit both for public APIs
 * that require no authentication.
 */
export interface OpenAPIConnectionDefinition {
    /**
     * The OpenAPI 3.x or Swagger 2.0 document. Pass an HTTPS URL to fetch
     * and parse at runtime, or an inline parsed object.
     */
    readonly spec: OpenAPISpecSource;
    /**
     * Base URL the runtime resolves operation paths against (e.g.
     * `https://api.example.com`).
     *
     * Optional: when omitted, the runtime uses the document's first usable
     * `servers` entry (OpenAPI 3.x) or `schemes`/`host`/`basePath`
     * (Swagger 2.0). It fills server-variable `{var}` placeholders from
     * each variable's `default`, and resolves a relative server URL
     * against the spec's URL. Provide `baseUrl` when the document has no
     * derivable base URL, or to override it.
     */
    readonly baseUrl?: string;
    /**
     * Human-readable summary of the connection and its operations.
     *
     * The system prompt layer uses it to describe the connection to the
     * model, and `connection_search` results use it so the model can
     * choose which connection to query.
     */
    readonly description: string;
    /**
     * Auth strategy for the API. The runtime sends the resolved token as
     * `Authorization: Bearer <token>`.
     *
     * - `getToken`-only: covers static API keys, pre-provisioned tokens,
     *   and out-of-band OAuth. Defaults to `principalType: "app"` when
     *   omitted.
     * - Three-method form: provide `startAuthorization` and
     *   `completeAuthorization` together to opt into interactive OAuth.
     *
     * Optional when `headers` is provided for non-Bearer auth schemes.
     */
    auth?: ConnectionAuthDefinition;
    /**
     * Optional per-connection approval gate for connection tool calls.
     *
     * Use the helpers from `eve/tools/approval`:
     * - `never()`: allow all tool calls without approval
     * - `once()`: require approval only the first time per session
     * - `always()`: require approval for every tool call
     */
    approval?: (ctx: NeedsApprovalContext) => boolean;
    /**
     * Arbitrary HTTP headers sent with every request to the API.
     *
     * Use for non-Bearer auth (e.g. API key headers) or configuration
     * headers. Can be combined with `auth`.
     */
    headers?: HeadersDefinition;
    /**
     * Operation filter keyed on `operationId`. When set, the model sees
     * only operations whose id passes the filter; `connection_search`
     * drops all others.
     *
     * Specify exactly one of `allow` or `block`. Mirrors `tools` on MCP
     * connections, but names operations rather than tools.
     */
    operations?: ToolFilterDefinition;
}
/**
 * Defines an OpenAPI connection.
 *
 * Validates the auth shape at definition time, in particular the
 * "both-or-neither" constraint for `startAuthorization` and
 * `completeAuthorization`: providing exactly one is a definition error.
 * `getToken` alone is valid and selects the non-interactive flow;
 * providing both opts into interactive OAuth.
 */
export declare function defineOpenAPIConnection(definition: OpenAPIConnectionDefinition): OpenAPIConnectionDefinition;