/**
 * Settings resolution for the shell application.
 *
 * Settings arrive from three places, lowest precedence first: the built-in
 * {@link DEFAULT_SETTINGS}, the per-user global file (under the profile
 * directory), and the per-project file (under the working directory). They are
 * merged shallowly with the rule "later wins", so a project file overrides the
 * global file, which overrides the defaults.
 *
 * The loader is deliberately forgiving. A missing file, an unreadable file, or a
 * file holding malformed/invalid JSON is treated as "no settings supplied at
 * this layer" — never an exception. Configuration problems must not stop the
 * agent from booting; the worst case is that the user falls back to defaults.
 *
 * Model selection is resolved separately by {@link resolveModelId}, which layers
 * an explicit per-invocation override on top of the configured default and a
 * hard-coded final fallback, validating each candidate against the catalog.
 */
import type { ServerConfig } from "../../interop";
import type { Locator } from "./locator";
/**
 * Which built-in tool collection the agent exposes to the model.
 *
 *   - `read-only` — observe-only tools (read, ls, grep, find, web).
 *   - `coding`    — read-only plus mutating/stateful tools (write, edit, bash…).
 *   - `all`       — every registered tool.
 *
 * Mirrors the `ToolCollection` names the capabilities layer defines; kept as a
 * standalone literal so settings need not import the capabilities package.
 */
export type ToolCollectionName = "read-only" | "coding" | "all";
/** Tool-related preferences. */
export interface ToolSettings {
    /** Which built-in collection to expose; absent leaves the choice to the host. */
    readonly collection?: ToolCollectionName;
}
/** History-condensation preferences, mirroring the runtime's policy shape. */
export interface CompactionSettings {
    /** Fraction of the context window (0..1) at which condensation triggers. */
    readonly triggerRatio?: number;
    /** Number of trailing turns kept untouched during condensation. */
    readonly keepRecent?: number;
}
/**
 * The user-tunable configuration surface.
 *
 * Every field is optional: an empty object is a valid {@link Settings}. Unknown
 * keys read off disk are tolerated and discarded during normalization.
 */
export interface Settings {
    /** The model id bound to runs when no per-invocation override is given. */
    readonly defaultModel?: string;
    /** A system preamble prepended to every model invocation. */
    readonly systemPrompt?: string;
    /** Tool exposure preferences. */
    readonly tools?: ToolSettings;
    /** External MCP servers to connect on start-up. */
    readonly mcpServers?: readonly ServerConfig[];
    /** History-condensation tuning. */
    readonly compaction?: CompactionSettings;
}
/**
 * The built-in baseline every layer is merged on top of.
 *
 * Intentionally minimal: it names a sensible default collection and leaves model
 * selection to {@link resolveModelId}'s fallback so the catalog stays the single
 * source of truth for valid model ids.
 */
export declare const DEFAULT_SETTINGS: Settings;
/**
 * Resolve the effective settings for a working directory.
 *
 * Merges three layers in increasing precedence — built-in defaults, the global
 * profile file, then the project file under `cwd` — and returns the result.
 * Never throws: any layer that cannot be read or parsed simply contributes
 * nothing. Reads run concurrently; the merge order is fixed regardless.
 */
export declare function loadSettings(locator: Locator, cwd: string): Promise<Settings>;
/**
 * Decide which model id a run should bind to.
 *
 * Precedence, highest first:
 *   1. `invocationModel` — an explicit per-invocation override (e.g. a CLI flag),
 *      used when it names a model the catalog knows.
 *   2. `settings.defaultModel` — the configured default, used when valid.
 *   3. {@link FALLBACK_MODEL_ID} — a catalog-guaranteed last resort.
 *
 * Each candidate is validated with {@link getCard}; an unknown id is skipped
 * rather than honored, so a stale or mistyped model never reaches the gateway.
 */
export declare function resolveModelId(settings: Settings, invocationModel?: string): string;
