Presets and context

/** Structural port: both MCP SDK generations can supply a connected Client. */
export interface MCPResourceClient {
    readResource(params: {
        uri: string;
    }, options?: {
        signal?: AbortSignal;
        timeout?: number;
        cacheMode?: "bypass";
    }): Promise<{
        contents: readonly {
            uri: string;
            mimeType?: string;
            text?: string;
            blob?: string;
        }[];
    }>;
}

export interface MCPResourceGrant {
    /** Exact server URI, never a local path or a URL fetched by the harness. */
    uri: string;
    /** Explicit text formats. A missing MIME is accepted only when listed as "". */
    mimeTypes: readonly string[];
}

export interface MCPResourcesOptions {
    id: string;
    /** Creates a principal-scoped connection for this binding. Authentication belongs to the host. */
    connect: (ctx: RunContext) => Promise<{
        client: MCPResourceClient;
        dispose?: () => Promise<void>;
    }>;
    /** Bounds setup even when the host connection factory ignores cancellation. Default 5000. */
    connectTimeoutMs?: number;
    resources: readonly MCPResourceGrant[];
    /** Rechecked before reading and before returning content, including on every subsequent fetch. */
    authorize: (grant: MCPResourceGrant, ctx: RunContext) => boolean | Promise<boolean>;
    /** Optional host selector, constrained to the declared grants. No server-wide discovery. */
    select?: (query: string, ctx: RunContext) => readonly string[] | Promise<readonly string[]>;
}

export declare const mcpResources: Ability<MCPResourcesOptions>;

export interface BaseOptions {
    id?: string;
    abilities?: readonly LocalAbilityUse[];
    defaults?: HarnessDefaults;
}

export interface FileContextOptions {
    id: string;
    /** Explicit host grant. Must be absolute; filesystem access begins only during fetch. */
    root: string;
    files: readonly string[];
}

export interface ResearchOptions extends BaseOptions {
    text?: TextContextOptions;
    files?: FileContextOptions;
    tools?: readonly ToolDef[];
}

export interface SuppliedToolsOptions {
    tools: readonly ToolDef[];
    requirements?: readonly string[];
}

export interface TextContextOptions {
    id: string;
    entries: readonly {
        id: string;
        text: string;
        uri?: string;
    }[];
}

/** Minimal local composition, no background jobs, learning, tools or provider selected implicitly. */
export declare function base(options?: BaseOptions): HarnessDefinition;

export declare const fileContext: Ability<FileContextOptions>;

/** Real context sources plus application-supplied research tools; no connector credentials or implicit web calls. */
export declare function research(options?: ResearchOptions): HarnessDefinition;

export declare const suppliedTools: Ability<SuppliedToolsOptions>;

export declare const textContext: Ability<TextContextOptions>;