import { ReferenceScope, ReferenceSourceService, LoadSidebarGroupsResult, ReferenceNode, NodeRef, ListChildrenResult, SearchInput, SearchResult, ReferencePreview, SelectedReference, ReferenceSourceRegistry } from './contracts/index.js';
import { WorkspaceFileOpenWithApplication } from '@tutti-os/workspace-file-manager/services';

interface ReferenceReadRequestCoordinator {
    request<T>(key: string, load: (signal: AbortSignal) => Promise<T>, consumerSignal?: AbortSignal): Promise<T>;
    invalidate(predicate?: (key: string) => boolean): void;
}
/**
 * 只协调正在执行的幂等读取，不保存成功结果或错误。
 *
 * 每个消费者拥有独立取消语义；只有最后一个消费者退出时才取消底层请求。
 */
declare function createReferenceReadRequestCoordinator(): ReferenceReadRequestCoordinator;

/**
 * 多源聚合器:根层级 = 每个可用源一个 folder 节点;其余按 node.ref.sourceId 委派。
 * 设计见 docs/architecture/agent-reference-source-services.md §3 / §4.4。
 */
/**
 * 源根节点的 nodeId 哨兵。由聚合器创建源根节点时使用;
 * 任何真实源都不会产出 nodeId 等于此值的子节点(workspace 源 nodeId 是路径,
 * app 源 nodeId 以 "app:" 开头),因此路由无歧义。
 */
declare const SOURCE_ROOT_NODE_ID = "\0source-root";
/** 顶部 tab 的描述(source 身份 + 能力)。 */
interface ReferenceSourceTab {
    sourceId: string;
    label: string;
    icon?: string;
    capabilities: ReferenceSourceService["capabilities"];
}
interface ReferenceSourceAggregator {
    /** 顶部 tab 列表:每个可用源一个 tab(已过滤 isAvailable、按 order 排序)。 */
    listSources(scope: ReferenceScope, input?: {
        signal?: AbortSignal;
    }): Promise<ReferenceSourceTab[]>;
    /** 每次 Picker 打开重新读取的左栏二级分组；不与目录 children 共享状态。 */
    loadSidebarGroups(scope: ReferenceScope, sourceId: string, input?: {
        cursor?: string | null;
        signal?: AbortSignal;
    }): Promise<LoadSidebarGroupsResult>;
    /** (备用,单树多根形态)根层级:每个可用源一个 folder 节点。 */
    listRoot(scope: ReferenceScope): Promise<ReferenceNode[]>;
    listChildren(scope: ReferenceScope, node: NodeRef, input?: {
        cursor?: string | null;
        filter?: string | null;
        signal?: AbortSignal;
    }): Promise<ListChildrenResult>;
    search(scope: ReferenceScope, sourceId: string, input: SearchInput): Promise<SearchResult>;
    createDirectory?(scope: ReferenceScope, sourceId: string, input: {
        parent: ReferenceNode | null;
        name: string;
    }): Promise<ReferenceNode>;
    open(scope: ReferenceScope, node: ReferenceNode): Promise<void>;
    listOpenWithApplications(scope: ReferenceScope, node: ReferenceNode): Promise<WorkspaceFileOpenWithApplication[]>;
    openWithApplication(scope: ReferenceScope, node: ReferenceNode, applicationPath: string): Promise<void>;
    openWithOtherApplication(scope: ReferenceScope, node: ReferenceNode, applicationPickerPrompt?: string): Promise<void>;
    reveal(scope: ReferenceScope, node: ReferenceNode): Promise<void>;
    readPreview(scope: ReferenceScope, node: ReferenceNode): Promise<ReferencePreview | null>;
    resolveSelection(node: ReferenceNode): SelectedReference;
    prepareSelection(scope: ReferenceScope, node: ReferenceNode): Promise<SelectedReference>;
    /**
     * 把语义定位参数解析为某源内从根到目标分组的 NodeRef 路径(root → leaf)。
     * 源未实现 locateTarget / 未找到时返回 null。需先 listSources/listRoot 触发源加载。
     */
    locateTarget(scope: ReferenceScope, sourceId: string, params: Record<string, string>): Promise<NodeRef[] | null>;
    /** 取已加载的源(用于读取 capabilities/metadata)。需先 listRoot 触发加载。 */
    getLoadedSource(sourceId: string): ReferenceSourceService | undefined;
    /**
     * 权限或 Host 能力变化时取消本聚合器的在途读取。
     * 成功结果本就不会被 Request Coordinator 保存。
     */
    invalidateRuntimeReads(scope?: ReferenceScope): void;
}
interface CreateReferenceSourceAggregatorOptions {
    /** 可跨多个 Picker 共享；只去重正在执行的幂等读取。 */
    requestCoordinator?: ReferenceReadRequestCoordinator;
    /** 共享 coordinator 时用于隔离不同 registry/用途。 */
    requestNamespace?: string;
    /** 权限或 Host 能力变化时由宿主递增，使旧请求键立即失效。 */
    getRequestEpoch?: () => string | number;
}
declare function isSourceRootNode(ref: NodeRef): boolean;
declare function createReferenceSourceAggregator(registry: ReferenceSourceRegistry, options?: CreateReferenceSourceAggregatorOptions): ReferenceSourceAggregator;
/** 静态 registry:持有一组源,按 isAvailable 过滤、按 order 排序。 */
declare function createStaticReferenceSourceRegistry(sources: readonly ReferenceSourceService[]): ReferenceSourceRegistry;

export { type CreateReferenceSourceAggregatorOptions as C, type ReferenceReadRequestCoordinator as R, SOURCE_ROOT_NODE_ID as S, type ReferenceSourceAggregator as a, type ReferenceSourceTab as b, createReferenceReadRequestCoordinator as c, createReferenceSourceAggregator as d, createStaticReferenceSourceRegistry as e, isSourceRootNode as i };