/**
 * The four CONTROL tools — built from ONE declarative table and a single factory.
 *
 * Where {@link CONNECTOR_TOOLS} (in core) describes the low-level passthrough tools
 * that talk straight to the {@link SaasBackend} port, this module defines the
 * higher-level *control surface* an agent uses to manage SaaS connectors as a
 * whole: discovering and hydrating toolkits into the live tool set, executing any
 * remote operation directly, opening an authorization flow, and reporting status.
 *
 * Two ideas, shared with the core builder, are reused verbatim here:
 *
 * 1. **One table, one factory.** The four control tools are rows in
 *    {@link CONTROL_SPECS}, each an `id` + `description` + JSON-Schema `parameters`
 *    + a `run(gateway, input)` thunk. {@link buildControlTools} maps the table to
 *    {@link DefinedTool}s with a single `defineTool` call per row — there is no
 *    `createEnableTool` / `createExecuteTool` family.
 * 2. **Delegate, don't reimplement.** Every `run` defers to the passed-in
 *    {@link SaasGateway}, which is the one object that owns the live registry, the
 *    discovery cache, the scope planner, and the connection state machine. The
 *    tools are thin command surfaces; the gateway holds the logic.
 *
 * The gateway is what distinguishes these from the core passthrough tools: a
 * control tool can mutate the live ToolBox (hydrating a toolkit's operations into
 * it) precisely because the gateway, not a bare backend, sits behind it.
 */
import type { DefinedTool, ToolResult } from "../../../capabilities";
import type { JsonSchema } from "../../../llmgateway/contract";
import type { SaasGateway } from "../gateway";
/** Read a string-array field from a loose argument bag, dropping non-strings/blanks. */
declare function readStringList(input: Record<string, unknown>, key: string): string[];
/**
 * One row of the control-tool table: a control tool described purely as data.
 *
 * Unlike the core `ControlToolSpec`, a control row's `run` is handed the
 * {@link SaasGateway} (the stateful façade), not a bare backend — that is what
 * lets `saas_enable` hydrate the live tool set.
 */
export interface ControlSpec {
    /** The model-facing tool name (e.g. `"saas_enable"`). */
    readonly id: string;
    /** Model-facing description of the control tool. */
    readonly description: string;
    /** JSON-Schema object for the control tool's parameters. */
    readonly parameters: JsonSchema;
    /** The control tool's behavior, expressed against the gateway façade. */
    run(gateway: SaasGateway, input: Record<string, unknown>): Promise<ToolResult>;
}
/**
 * The four control tools, as one declarative table.
 *
 * - `saas_enable` — hydrate a toolkit's operations into the live ToolBox so the
 *   agent can call them natively on subsequent turns.
 * - `saas_execute` — direct fallback execution of any remote operation by slug,
 *   without first hydrating it.
 * - `saas_connect` — start (and drive) an authorization flow for a toolkit.
 * - `saas_status` — list connected accounts and the operations currently in scope.
 */
export declare const CONTROL_SPECS: readonly ControlSpec[];
/**
 * Instantiate every row of {@link CONTROL_SPECS} into a {@link DefinedTool}, each
 * bound to the supplied {@link SaasGateway}.
 *
 * This is the single factory the spec calls for: one map over the data table, one
 * `defineTool` per row, no per-control-tool boilerplate.
 */
export declare function buildControlTools(gateway: SaasGateway): DefinedTool[];
export { readStringList };
