/**
 * Internal groundwork for a principal-scoped third-party MCP broker.
 *
 * This module deliberately has no stdio, HTTP, or public h2a MCP wiring. The
 * future gateway owns authenticated ingress and turns its authenticated `sub`
 * into an AuthenticatedPrincipal before it creates this broker.
 */
declare const authenticatedPrincipalBrand: unique symbol;
declare const secretRefBrand: unique symbol;
/** A subject established by the broker ingress, never an agent tool argument. */
export type AuthenticatedPrincipal = string & {
    readonly [authenticatedPrincipalBrand]: "AuthenticatedPrincipal";
};
/**
 * Opaque vault reference. This is the only credential-shaped value in the
 * broker types: it names server-held material, it does not contain that
 * material.
 */
export type SecretRef = string & {
    readonly [secretRefBrand]: "SecretRef";
};
/** Construct server-side opaque values at trusted integration boundaries. */
export declare function authenticatedPrincipal(sub: string): AuthenticatedPrincipal;
/** Construct a server-side vault handle; no credential value is accepted. */
export declare function secretRef(ref: string): SecretRef;
export interface RegistryToolInputSchema {
    readonly type: "object";
    readonly properties: {
        readonly query: {
            readonly type: "string";
            readonly description?: string;
        };
    };
    readonly required: readonly ["query"];
    readonly additionalProperties: false;
}
/** The complete tool shape an agent may receive from this module. */
export interface AgentVisibleRegistryTool {
    readonly name: string;
    readonly description: string;
    readonly inputSchema: RegistryToolInputSchema;
}
/** The only agent-supplied shape accepted by this one-server increment. */
export interface AgentVisibleRegistryArguments {
    readonly query: string;
}
/** The reviewed, agent-visible result shape for the one read-only mail operation. */
export interface AgentVisibleRegistryOutput {
    readonly kind: "mail.search.result";
    readonly messages: readonly {
        readonly id: string;
        readonly subject: string;
    }[];
}
/**
 * Adapter-side reviewed data. This is intentionally not the object returned to
 * an agent: the broker constructs the closed AgentVisibleRegistryOutput DTO.
 */
export interface ReviewedMailSearchResult {
    readonly messages: readonly {
        readonly id: string;
        readonly subject: string;
    }[];
}
/** A reviewed, pinned descriptor. It is never learned from upstream tools/list. */
export interface ReviewedRegistryServer {
    readonly id: string;
    readonly tools: readonly AgentVisibleRegistryTool[];
}
/**
 * Server-side authorization record. `secretRef` is intentionally opaque and
 * is absent from every agent-visible result type below.
 */
export interface ConnectorGrant {
    readonly connectorRef: string;
    readonly serverId: string;
    readonly secretRef: SecretRef;
    readonly mayUseToolNames: readonly string[];
    readonly active: boolean;
}
export interface Established<T> {
    readonly kind: "established";
    readonly state: "success";
    readonly value: T;
    readonly asOf: string;
}
/**
 * A non-success resolution is intentionally open-ended. Broker code recognizes
 * only the positive `established` state, so a newly added failure state cannot
 * be mistaken for an established empty collection.
 */
export interface NonEstablishedResolution {
    readonly kind: string;
    readonly state: "failure";
    readonly source: string;
    readonly code: string;
    readonly retryable: boolean;
    readonly observedAt: string;
}
export type RegistryResolution<T> = Established<T> | NonEstablishedResolution;
export declare function established<T>(value: T, asOf?: string): Established<T>;
export declare function isEstablished<T>(resolution: RegistryResolution<T>): resolution is Established<T>;
export interface PrincipalGrantResolver {
    resolve(principal: AuthenticatedPrincipal): RegistryResolution<readonly ConnectorGrant[]>;
}
/** Executor-only call: the opaque secret reference never enters agent-visible types. */
export interface RegistryUpstreamAdapter {
    invoke(input: {
        readonly connectorRef: string;
        readonly secretRef: SecretRef;
        readonly tool: AgentVisibleRegistryTool;
        readonly arguments: AgentVisibleRegistryArguments;
        readonly correlationId: string;
    }): RegistryResolution<ReviewedMailSearchResult>;
}
export interface RegistryAuditEvent {
    readonly principalRef: string;
    readonly connectorRef: string | undefined;
    readonly toolName: string | undefined;
    readonly outcome: "listed" | "called" | "unavailable" | "not_authorized" | "invalid_arguments";
    readonly correlationId: string | undefined;
    readonly observedAt: string;
}
export interface PrincipalScopedRegistryBrokerOptions {
    readonly principal: AuthenticatedPrincipal;
    readonly catalogue: readonly ReviewedRegistryServer[];
    readonly grantResolver: PrincipalGrantResolver;
    readonly adapters: Readonly<Record<string, RegistryUpstreamAdapter>>;
    readonly audit?: (event: RegistryAuditEvent) => void;
    readonly now?: () => string;
}
export interface RegistryToolsEstablished {
    readonly kind: "established";
    readonly tools: readonly AgentVisibleRegistryTool[];
    readonly asOf: string;
}
export type RegistryUnavailableSource = "catalogue" | "binding" | "grant" | "credential" | "upstream" | "adapter";
export type RegistryUnavailableCode = "source_unavailable" | "upstream_timeout" | "upstream_protocol_error" | "adapter_not_available";
export interface RegistryUnavailable {
    readonly kind: "unavailable";
    readonly source: RegistryUnavailableSource;
    readonly code: RegistryUnavailableCode;
    readonly retryable: boolean;
    readonly observedAt: string;
}
/** The only two possible discovery results: established (including empty), or unavailable. */
export type RegistryToolsResult = RegistryToolsEstablished | RegistryUnavailable;
export interface RegistryCallCompleted {
    readonly kind: "completed";
    readonly output: AgentVisibleRegistryOutput;
}
export interface RegistryNotAuthorized {
    readonly kind: "not_authorized";
}
export interface RegistryInvalidArguments {
    readonly kind: "invalid_arguments";
}
export type RegistryCallResult = RegistryCallCompleted | RegistryUnavailable | RegistryNotAuthorized | RegistryInvalidArguments;
export interface PrincipalScopedRegistryBroker {
    /** Returns only this principal's effective mayUse projection, never the catalogue or grants. */
    listTools(): RegistryToolsResult;
    /** Re-resolves grants before every call; a previous list is never authorization. */
    callTool(input: {
        readonly name: string;
        readonly arguments: AgentVisibleRegistryArguments;
        readonly correlationId: string;
    }): RegistryCallResult;
}
/**
 * Creates one broker projection for one ingress-authenticated principal.
 * The caller supplies the principal at construction time, not as agent data.
 */
export declare function createPrincipalScopedRegistryBroker(options: PrincipalScopedRegistryBrokerOptions): PrincipalScopedRegistryBroker;
export {};
//# sourceMappingURL=broker.d.ts.map