import { ReferenceNode, NodeRef, SelectedReference, WorkspaceFileReference, ReferenceSourceCapabilities, ReferenceScope, ReferenceSearchPagination, ReferenceHandle, WorkspaceFileReferenceAdapter, ReferenceSourceService, ReferenceProvenanceCatalog, ReferenceProvenanceFilter, ReferenceProvenanceOption, ReferenceProvenanceDimension } from '../contracts/index.js';
export { C as CreateReferenceSourceAggregatorOptions, R as ReferenceReadRequestCoordinator, a as ReferenceSourceAggregator, b as ReferenceSourceTab, S as SOURCE_ROOT_NODE_ID, c as createReferenceReadRequestCoordinator, d as createReferenceSourceAggregator, e as createStaticReferenceSourceRegistry, i as isSourceRootNode } from '../referenceSourceAggregator-CC-K1EfG.js';
import '@tutti-os/workspace-file-manager/services';
import '@tutti-os/workspace-file-preview';

/**
 * Reference Source Services 的共享 base 工具(形状处理,非取数)。
 * 设计见 docs/architecture/agent-reference-source-services.md §1 / §2。
 */
/**
 * 「回到源根」哨兵 nodeId。源在 loadSidebarGroups 里用它表示一个等价于源根的
 * 二级分组(如本地源的「个人」= 用户 home 根);picker 选中它走 navigateToRoot
 * 而非 ensureChildren,避免把哨兵当真实路径打后端。
 */
declare const WORKSPACE_ROOT_GROUP_NODE_ID = "__workspace_root__";
/** 节点的全局 key,用于 picker 树状态索引与去重。picker 不解析其内部结构。 */
declare function nodeRefKey(ref: NodeRef): string;
declare function nodeKey(node: ReferenceNode): string;
/** 任意输入归一为 "file" | "folder"。 */
declare function normalizeReferenceNodeKind(kind: string | null | undefined): "file" | "folder";
/** folder 在前、同类按 displayName 本地化排序。 */
declare function sortReferenceNodes(nodes: readonly ReferenceNode[]): ReferenceNode[];
/** 按 node key 去重,保留首次出现。支持 cursor append 的稳定去重。 */
declare function dedupeReferenceNodes(nodes: readonly ReferenceNode[]): ReferenceNode[];
/** 续页累积:把新一页 append 到已有项后并去重(cursor 语义,不重排)。 */
declare function appendReferencePage(current: readonly ReferenceNode[], next: readonly ReferenceNode[]): ReferenceNode[];
/** SelectedReference 与现有 WorkspaceFileReference 形状兼容,便于下游零改动复用。 */
declare function selectedReferenceToWorkspaceFileReference(selected: SelectedReference): WorkspaceFileReference;

/**
 * 统一的「引用列表协议」—— 与 app references 同一套 group/reference/parentGroupId/cursor 形状。
 * 各源(应用 / issue / 任务…)各自实现一个 ReferenceListBackend 把自家数据映射成此协议;
 * createReferenceListSource 把协议 item 映射成 ReferenceNode,各源前端逻辑完全复用。
 * 当前架构见 docs/architecture/agent-reference-sources.md。
 */
interface ReferenceListGroup {
    type: "group";
    /** 不透明分组 id;作为下钻的 parentGroupId 原样回传。 */
    id: string;
    displayName: string;
    /** 可选的展示上下文,用于详情/搜索副标题,避免 UI 泄露不透明 group id。 */
    parentLabel?: string | null;
    referenceCount?: number | null;
    /** 可选分组图标(data URL / 远程 URL),如应用产物源的 app 图标。 */
    iconUrl?: string | null;
}
interface ReferenceListFile {
    /** daemon/host 可解析的文件路径。 */
    path: string;
    displayName?: string | null;
    /**
     * 可选的归属标签(如应用名 / 议题标题),用于搜索结果副标题。
     * 各源在「跨整源搜索拍平」时填入父级上下文;不填则不展示副标题。
     */
    parentLabel?: string | null;
    createdTimeMs?: number | null;
    sizeBytes?: number | null;
    mtimeMs?: number | null;
    mimeType?: string | null;
}
interface ReferenceListReference {
    type: "reference";
    reference: ReferenceListFile;
}
type ReferenceListItem = ReferenceListGroup | ReferenceListReference;
interface ReferenceListRequest {
    /** null = 根层级。 */
    parentGroupId: string | null;
    cursor?: string | null;
    filter?: string | null;
    signal?: AbortSignal;
}
interface ReferenceListResult {
    items: ReferenceListItem[];
    nextCursor?: string | null;
}
interface ReferenceListSearchResult extends ReferenceListResult {
    /** Per-query override for the source's default search pagination mode. */
    searchPagination?: ReferenceSearchPagination;
}
/** 递归搜索请求(跨整源,非当前层 filter)。 */
interface ReferenceListSearchRequest {
    query: string;
    /** 结果类型约束,backend 必须在分页/limit 前执行。 */
    kinds?: Array<ReferenceNode["kind"]>;
    /** 已选文件类型筛选分类 id(全局统一口径);空数组/缺省 = 不按类型过滤。 */
    filters?: string[];
    cursor?: string | null;
    limit?: number;
    signal?: AbortSignal;
    /**
     * 可选:把搜索限定在某个分组下(协议层不透明 group id,与 list 返回的 group.id 同形)。
     * 缺省/null = 跨整源搜索。由 createReferenceListSource 从 SearchInput.withinNodeId 解码而来。
     */
    withinGroupId?: string | null;
}
/** 各源自治的取数适配器:把自家数据映射成统一协议。 */
interface ReferenceListBackend {
    list(scope: ReferenceScope, request: ReferenceListRequest): Promise<ReferenceListResult>;
    /**
     * 可选:递归搜索。实现即代表该源支持全局搜索(对应 capabilities.searchable)。
     * 返回 flat reference items(协议层不返回 group)。
     */
    search?(scope: ReferenceScope, request: ReferenceListSearchRequest): Promise<ReferenceListSearchResult>;
    /**
     * 可选:把语义定位参数解析为从根到目标分组的「不透明分组 id」路径(root → leaf),
     * 用各源自家的 group id 方案(与 list 返回的 group.id 同形),wrapper 负责编成 NodeRef。
     * 返回 null 表示不支持或未找到。
     */
    locate?(scope: ReferenceScope, params: Record<string, string>): Promise<string[] | null>;
    /**
     * 可选:把自家「不透明分组 id」解码成可被 agent 解析的领域句柄(见 ReferenceHandle)。
     * navigable 源实现;wrapper 负责先剥掉 GROUP_PREFIX 再调本方法。
     */
    describeHandle?(groupId: string): ReferenceHandle | null;
}
interface CreateReferenceListSourceInput {
    sourceId: string;
    label: string;
    order?: number;
    /** 可选源图标令牌(如 "issue"),供 picker 决定二级分组的兜底图标。 */
    icon?: string;
    capabilities: ReferenceSourceCapabilities;
    isAvailable: (scope: ReferenceScope) => boolean | Promise<boolean>;
    backend: ReferenceListBackend;
    /** 保留 backend.list 返回的数组顺序，禁止 picker 按名称重新排序。 */
    preserveBackendOrder?: boolean;
    /** open/preview 复用 host 链路(协议返回的 path 可被解析打开)。 */
    adapter: WorkspaceFileReferenceAdapter;
}
declare function createReferenceListSource(input: CreateReferenceListSourceInput): ReferenceSourceService;
/** UTF-8 安全的 base64url(浏览器/Node 通用)。 */
declare function base64UrlEncode(value: string): string;
declare function base64UrlDecode(value: string): string;

/**
 * 全局统一「文件类型筛选分类」。浏览态递归投影源树并仅保留含匹配文件的目录;
 * 关键字搜索时,search() 接收的 filters 即此处的分类 id 数组,各源 daemon 在
 * 分页/limit 前按扩展名或媒体类型过滤。
 *
 * 这是分类口径的「单一 TS 来源」。其余各处均为逐字镜像,改一处务必同步全部:
 *   - Go 宿主侧:services/tuttid/data/workspace/reference_filter_categories.go
 *   - group-chat 应用:apps/server/src/domains/reference-filter-categories.ts
 *   - vibe-design 应用:server/src/routes/references-routes.ts
 *   - ai-media-canvas 应用:apps/server/src/http/references.ts
 *   - app_factory 技能契约:app_factory_reference/references/manifest-contract.md
 *   - TSH desktopd:tutti-lab/tsh/cmd/desktopd/biz/workspacefs/workspacefs.go
 *     (`workspaceFileManagerExtensionsByCategory`)
 *
 * 分类口径:image(图片)/ video(视频)/ document(文档,含表格)/ webpage(网页)/ other(其他)。
 * 音频、代码、压缩包等未单列扩展名,统一归入 "other" 兜底。
 */
type ReferenceFilterCategoryId = "image" | "video" | "document" | "webpage" | "other";
interface ReferenceFilterCategory {
    id: ReferenceFilterCategoryId;
    /** 展示名走 i18n:referencePicker 命名空间下的 copy key,由 UI 层解析。 */
    labelKey: string;
    /** 该分类归属的文件扩展名(小写,不含点)。"other" 为空,表示「未收录/无扩展名」兜底。 */
    extensions: readonly string[];
}
/**
 * 分类定义(展示顺序即数组顺序)。每个分类按文件扩展名归类;
 * 文件夹不参与类型过滤(始终保留以便继续下钻)。
 */
declare const REFERENCE_FILTER_CATEGORIES: readonly ReferenceFilterCategory[];
/** 从文件名末段推断分类;无扩展名或未收录的扩展名归入「other」。 */
declare function categoryOfFileName(name: string): ReferenceFilterCategoryId;
/**
 * 分类筛选判定:空 ids = 不筛选(全部通过);文件夹始终通过(保留导航能力);
 * 仅对文件按其分类匹配。供需要在客户端兜底过滤的调用方复用。
 */
declare function matchesFilterCategories(name: string, isFolder: boolean, filterIds: readonly string[]): boolean;

interface ReferenceProvenanceAgentLabelParts {
    agentLabel: string;
    ownerLabel: string;
}
declare function resolveReferenceProvenanceAgentLabelParts(option: ReferenceProvenanceOption, memberOptionsById: ReadonlyMap<string, ReferenceProvenanceOption>): ReferenceProvenanceAgentLabelParts | null;
declare function normalizeReferenceProvenanceCatalog(catalog: ReferenceProvenanceCatalog): ReferenceProvenanceCatalog;
declare function normalizeReferenceProvenanceIds(ids: readonly string[] | null | undefined, options: readonly ReferenceProvenanceOption[]): readonly string[] | null;
declare function normalizeReferenceProvenanceFilter(filter: ReferenceProvenanceFilter, catalog: ReferenceProvenanceCatalog): ReferenceProvenanceFilter;
declare function referenceProvenanceFilterIsActive(filter: ReferenceProvenanceFilter | null | undefined): boolean;
declare function referenceProvenanceFilterIds(filter: ReferenceProvenanceFilter, dimension: ReferenceProvenanceDimension): readonly string[] | null;
declare function withReferenceProvenanceFilterIds(filter: ReferenceProvenanceFilter, dimension: ReferenceProvenanceDimension, ids: readonly string[] | null): ReferenceProvenanceFilter;
declare function referenceProvenanceFilterCacheKey(filter: ReferenceProvenanceFilter): string;
declare function toggleReferenceProvenanceFilterId(filter: ReferenceProvenanceFilter, catalog: ReferenceProvenanceCatalog, dimension: ReferenceProvenanceDimension, rawId: string): ReferenceProvenanceFilter;
declare function toggleAllReferenceProvenanceFilterIds(filter: ReferenceProvenanceFilter, catalog: ReferenceProvenanceCatalog, dimension: ReferenceProvenanceDimension): ReferenceProvenanceFilter;

declare const REFERENCE_SEARCH_CURSOR_EXPIRED_ERROR_CODE = "reference.search_cursor_expired";
declare const REFERENCE_SEARCH_CURSOR_LOOP_ERROR_CODE = "reference.search_cursor_loop";
declare class ReferenceSearchCursorExpiredError extends Error {
    readonly code = "reference.search_cursor_expired";
    constructor(options?: ErrorOptions);
}
declare class ReferenceSearchCursorLoopError extends Error {
    readonly code = "reference.search_cursor_loop";
    constructor(options?: ErrorOptions);
}
declare function isReferenceSearchCursorExpiredError(error: unknown): error is ReferenceSearchCursorExpiredError;

declare function uniqueWorkspaceFileReferences(refs: readonly WorkspaceFileReference[]): WorkspaceFileReference[];

export { type CreateReferenceListSourceInput, REFERENCE_FILTER_CATEGORIES, REFERENCE_SEARCH_CURSOR_EXPIRED_ERROR_CODE, REFERENCE_SEARCH_CURSOR_LOOP_ERROR_CODE, type ReferenceFilterCategory, type ReferenceFilterCategoryId, type ReferenceListBackend, type ReferenceListFile, type ReferenceListGroup, type ReferenceListItem, type ReferenceListReference, type ReferenceListRequest, type ReferenceListResult, type ReferenceListSearchRequest, type ReferenceListSearchResult, type ReferenceProvenanceAgentLabelParts, ReferenceSearchCursorExpiredError, ReferenceSearchCursorLoopError, WORKSPACE_ROOT_GROUP_NODE_ID, appendReferencePage, base64UrlDecode, base64UrlEncode, categoryOfFileName, createReferenceListSource, dedupeReferenceNodes, isReferenceSearchCursorExpiredError, matchesFilterCategories, nodeKey, nodeRefKey, normalizeReferenceNodeKind, normalizeReferenceProvenanceCatalog, normalizeReferenceProvenanceFilter, normalizeReferenceProvenanceIds, referenceProvenanceFilterCacheKey, referenceProvenanceFilterIds, referenceProvenanceFilterIsActive, resolveReferenceProvenanceAgentLabelParts, selectedReferenceToWorkspaceFileReference, sortReferenceNodes, toggleAllReferenceProvenanceFilterIds, toggleReferenceProvenanceFilterId, uniqueWorkspaceFileReferences, withReferenceProvenanceFilterIds };