/**
 * The {@link SaasGateway} — the stateful façade that assembles the SaaS connector
 * bridge into one runnable object.
 *
 * The `core/` layer is deliberately stateless: a port, a scope planner, a content
 * hash cache, a single remote-tool builder, a declarative control-tool table. The
 * `render/` layer is pure. What was missing was the thing that *owns state* and
 * wires those pieces together: a live {@link ToolRegistry} that hydrated remote
 * tools are registered into, a {@link ScopePlanner} that records what is in scope,
 * a {@link HashCache} that dedupes repeated `enableToolkit` work by content hash,
 * and the {@link CONNECT_RULES}-driven connection driver. That is this gateway.
 *
 * It exposes three tool surfaces and the verbs the control tools delegate to:
 *
 * - {@link SaasGateway.controlToolBox} — just the four control tools
 *   (`saas_enable` / `saas_execute` / `saas_connect` / `saas_status`), the surface
 *   an agent starts with before any toolkit is hydrated.
 * - {@link SaasGateway.enableToolkit} — list a toolkit's remote operations, wrap
 *   each into a native {@link DefinedTool} via the core builder, register them into
 *   the live registry, and content-hash-cache the resulting defs so a second enable
 *   of the same shape is a no-op that returns the very same tools.
 * - {@link SaasGateway.toolBox} — the control tools plus every remote tool hydrated
 *   so far, the surface to hand the model once toolkits are live.
 *
 * Nothing here imports the vendor SDK: the gateway depends only on the
 * {@link SaasBackend} port. {@link createComposioGateway} is the one convenience
 * that pairs this gateway with the real Composio adapter.
 */
import type { DefinedTool, ToolResult } from "../../capabilities";
import type { ToolBox } from "../../runtime/contract";
import { type SaasBackend, type ConnectedAccount } from "./core/index";
import { type AwaitOptions } from "./control/connect";
/**
 * The outcome of hydrating a toolkit, returned by {@link SaasGateway.enable} and
 * rendered by the `saas_enable` control tool. `hydrated` is the model-facing names
 * of the tools now callable; `tools` are the {@link DefinedTool}s themselves.
 */
export interface EnableReport {
    /** The toolkit that was hydrated. */
    readonly toolkit: string;
    /** The model-facing names of the now-callable remote tools. */
    readonly hydrated: readonly string[];
    /** The hydrated tool objects (same identities a second cached enable returns). */
    readonly tools: readonly DefinedTool[];
    /** True when this enable was served entirely from the content-hash cache. */
    readonly cached: boolean;
}
/**
 * The outcome of driving a connection flow, returned by {@link SaasGateway.connect}
 * and rendered by the `saas_connect` control tool. `action` mirrors the terminal
 * {@link ConnectOutcome} the rule-table driver settled on.
 */
export interface ConnectReport {
    /** The toolkit the connection targeted. */
    readonly toolkit: string;
    /** The terminal disposition of the attempt. */
    readonly action: "done" | "await-auth" | "expired" | "failed";
    /** The connection request id that was driven. */
    readonly requestId: string;
    /** The authorization URL to surface, when the user still has to act. */
    readonly authUrl?: string;
    /** The connected-account id, once the link went active. */
    readonly accountId?: string;
    /** A human-readable failure reason when `action` is `"failed"`. */
    readonly reason?: string;
}
/** A point-in-time snapshot of the bridge's connection + scope state. */
export interface StatusReport {
    /** The user's connected accounts, as the backend reports them. */
    readonly accounts: readonly ConnectedAccount[];
    /** The model-facing names of every remote tool currently in scope. */
    readonly enabledTools: readonly string[];
}
/** Tuning knobs for {@link createSaasGateway}. */
export interface SaasGatewayOptions {
    /** Pin all remote execution to one connected account; omit to let the backend pick. */
    readonly accountId?: string;
    /** Connection-driver pacing/bounding, forwarded to {@link initiateAndAwait}. */
    readonly connect?: Pick<AwaitOptions, "pollIntervalMs" | "maxPolls" | "sleep">;
}
/**
 * The stateful façade over the SaaS connector bridge.
 *
 * The verbs ({@link SaasGateway.enable}, {@link SaasGateway.execute},
 * {@link SaasGateway.connect}, {@link SaasGateway.status}) are what the control
 * tools delegate to; the three `*ToolBox` / `enableToolkit` methods are the
 * assembly surface a host wires into an agent session.
 */
export interface SaasGateway {
    /** The backend port this gateway drives. */
    readonly backend: SaasBackend;
    /** A {@link ToolBox} of just the four control tools. */
    controlToolBox(): ToolBox;
    /** A {@link ToolBox} of the control tools plus every hydrated remote tool. */
    toolBox(): ToolBox;
    /**
     * Hydrate a toolkit's remote operations into the live registry and return the
     * minted tools. Content-hash-cached: a second call with the same shape returns
     * the identical tool defs without re-listing or re-registering.
     */
    enableToolkit(name: string, only?: readonly string[]): Promise<DefinedTool[]>;
    /** The verb behind `saas_enable`: hydrate a toolkit and report on it. */
    enable(toolkit: string, only?: readonly string[]): Promise<EnableReport>;
    /** The verb behind `saas_execute`: run one remote operation directly by slug. */
    execute(tool: string, args: unknown, accountId?: string): Promise<ToolResult>;
    /** The verb behind `saas_connect`: drive an authorization flow to a terminal state. */
    connect(toolkit: string, opts?: {
        callbackUrl?: string;
        authConfigId?: string;
    }): Promise<ConnectReport>;
    /** The verb behind `saas_status`: the current connection + scope picture. */
    status(): Promise<StatusReport>;
}
/**
 * Assemble a {@link SaasGateway} over a {@link SaasBackend}.
 *
 * The gateway owns a fresh {@link ScopePlanner}-driven scope, a live
 * {@link ToolRegistry}, and the content-hash enable cache from the moment it is
 * built; the four control tools are registered immediately so
 * {@link SaasGateway.controlToolBox} is usable before any toolkit is hydrated.
 */
export declare function createSaasGateway(backend: SaasBackend, opts?: SaasGatewayOptions): SaasGateway;
/**
 * Convenience: assemble a {@link SaasGateway} wired to the real Composio adapter.
 *
 * This is the one place the gateway touches the vendor seam, and it does so only
 * transitively — {@link createComposioBackend} is the lone `@composio/core`
 * importer. Hand it an API key and the returned gateway is ready to enable
 * toolkits against the live catalog.
 */
export declare function createComposioGateway(opts: {
    apiKey: string;
}): SaasGateway;
