import type { Capability, CapabilityEffect, JsonValue } from "./types.js";
export type AbilitySourceKind = "native" | "connector" | "mcp" | "openapi" | "npm" | "pypi" | "oci" | "repository" | "composition" | "gap";
export type AbilityCandidate = {
    kind: AbilitySourceKind;
    id: string;
    name?: string;
    description?: string;
    ready: boolean;
    trusted?: boolean;
    score?: number;
    effects?: readonly CapabilityEffect[];
    authorityComplete?: boolean;
    /** Whether the selected ability can execute immediately without a materialization/acquisition step. */
    executionReady?: boolean;
    metadata?: Record<string, JsonValue>;
};
export type AbilityProviderContext = {
    intent: string;
    input?: unknown;
    approved?: boolean;
};
export interface AbilityProvider {
    readonly id: string;
    readonly kind: AbilitySourceKind;
    readonly priority: number;
    readonly description: string;
    discover(context: AbilityProviderContext): Promise<readonly AbilityCandidate[]>;
    execute?(candidate: AbilityCandidate, context: AbilityProviderContext): Promise<unknown>;
    close?(): void | Promise<void>;
}
export type PreparedProviderReceipt = {
    receiptVersion: "0.1";
    provider: {
        id: string;
        kind: AbilitySourceKind;
    };
    ability: {
        id: string;
        name?: string;
    };
    status: "succeeded";
    effects: readonly CapabilityEffect[];
    authorityComplete: boolean;
    approved: boolean;
    inputHash: string;
    outputHash: string;
    startedAt: string;
    endedAt: string;
    upstreamReceipt?: unknown;
};
export type NeedResolution = {
    intent: string;
    status: "ready" | "executed" | "unresolved";
    provider?: string;
    source?: AbilitySourceKind;
    candidate?: AbilityCandidate;
    result?: unknown;
    receipt?: unknown;
    considered: {
        provider: string;
        kind: AbilitySourceKind;
        candidates: number;
        detail?: string;
    }[];
};
export declare class AbilityProviderRegistry {
    private readonly providers;
    register(provider: AbilityProvider): this;
    list(): readonly AbilityProvider[];
    close(): Promise<void>;
}
export type NeedOptions = Omit<AbilityProviderContext, "intent"> & {
    providers?: AbilityProviderRegistry;
    execute?: boolean;
    indexes?: readonly string[];
    pythonPackage?: string;
    pythonVersion?: string;
    ociImage?: string;
    ociArgs?: string[];
    externalOnly?: boolean;
    allowUnverifiedSource?: boolean;
    fetch?: typeof fetch;
    githubToken?: string;
};
/**
 * Turn an already-prepared set of capabilities into a preferred provider.
 *
 * This is the bridge used by MCP, OpenAPI, managed connectors, native packages,
 * and application-specific catalogs. It deliberately reuses CapabilityRuntime so
 * prepared integrations receive the same authorization and receipt semantics as
 * acquired software.
 */
export declare function providerFromCapabilities(options: {
    id: string;
    kind: Exclude<AbilitySourceKind, "gap">;
    priority?: number;
    description: string;
    capabilities: readonly Capability<any, any>[];
    trusted?: boolean;
}): AbilityProvider;
/**
 * Resolve an intent through the simplest production-ready provider first.
 *
 * Prepared providers are always consulted before Capability attempts package,
 * container, or repository acquisition. The caller asks for an ability; substrate
 * selection is an implementation detail unless diagnostics are requested.
 */
export declare function need(intent: string, options?: NeedOptions): Promise<NeedResolution>;
/** Convenience helper for prepared integrations discovered outside Capability core. */
export declare function defineAbilityProvider(provider: AbilityProvider): AbilityProvider;
//# sourceMappingURL=need.d.ts.map