/**
 * Adaptive Context Governor — output-reserve-aware pressure policy for ARC.
 *
 * The original ARC kernel is intentionally eager: a fixed 50K growth branch
 * can nudge at ~5-10% of a 1M window. That is useful for proving the mechanism,
 * but long-session measurements show repeated surface rewrites can cost more
 * uncached input than they save while the window still has ample headroom.
 *
 * Governor mode changes only the policy, not the reversible ARC storage:
 * - cap an excessive adapter default output reserve;
 * - derive the input budget left after output reserve and a safety margin;
 * - disable growth-only nudges;
 * - nudge only at a fraction of that effective input budget.
 * - retain a deterministic, reversible emergency fallback when the model
 *   ignores the late nudge or the provider confirms a real overflow.
 *
 * The result is deliberately stateless and auditable. A predictive controller
 * can be layered on later only if live evidence shows this simpler policy is
 * insufficient.
 * @module dsh-arc-context/governor
 */
import type { Session } from '@deepseek-ai/dsh-session';
import type { KernelConfigInput } from './config.ts';
/** Ordinary completion budget when no caller expressed long-output intent. */
export declare const DEFAULT_AUTO_OUTPUT_TOKENS = 32768;
/** Auto preserves explicit conversation intent; a number remains a hard cap. */
export type MaxOutputTokensPolicy = 'auto' | number;
export interface AdaptiveGovernorConfig {
    /** Enable output-reserve-aware late, batched ARC nudges. Default false. */
    readonly enabled: boolean;
    /** Intent-aware completion reserve (`auto`) or a hard cap. Default `auto`. */
    readonly maxOutputTokens: MaxOutputTokensPolicy;
    /** Capacity kept unused for estimation error and one in-flight step. Default 32768. */
    readonly safetyMarginTokens: number;
    /** Nudge line as a fraction of effective input capacity. Default 0.75. */
    readonly nudgeAtEffectiveCapacityPct: number;
    /** Emergency line as a fraction of effective input capacity. Default 0.90. */
    readonly emergencyAtEffectiveCapacityPct: number;
    /** Allow model-free reversible cold-storage at emergency pressure/overflow. Default true. */
    readonly emergencyFallback: boolean;
}
export interface GovernorCapacity {
    readonly contextWindow: number;
    readonly outputReserve: number;
    readonly safetyMargin: number;
    readonly effectiveInputLimit: number;
    readonly nudgeAtTokens: number;
    readonly emergencyAtTokens: number;
}
export declare const DEFAULT_ADAPTIVE_GOVERNOR: AdaptiveGovernorConfig;
/** Resolve and fail-fast validate governor configuration. */
export declare function resolveAdaptiveGovernor(input?: Partial<AdaptiveGovernorConfig>): AdaptiveGovernorConfig;
/**
 * Resolve one request's completion cap.
 *
 * Auto mode treats an omitted value as ordinary output (32K), while preserving
 * a caller's explicit long-output intent. Numeric mode is the operator's hard
 * ceiling and therefore keeps the historical min(explicit, configured) rule.
 */
export declare function governedMaxTokens(current: number | undefined, config: AdaptiveGovernorConfig): number | undefined;
/**
 * Read the durable conversation output intent before request derivation.
 * Adapter-materialized defaults are not user intent. A Governor-injected 32K
 * value is deliberately unmarked and becomes the stable conversation value.
 */
export interface OutputIntentContext {
    readonly session: Session;
    readonly options: object;
}
export declare function explicitMaxTokensForAgent(agent: OutputIntentContext): number | undefined;
/** Resolve the reserve used by this agent's pressure geometry. */
export declare function governedOutputReserve(agent: OutputIntentContext, config: AdaptiveGovernorConfig): number;
/** Compute the provider-safe input budget the pressure controller may consume. */
export declare function governorCapacity(contextWindow: number, config: AdaptiveGovernorConfig, outputReserve?: number): GovernorCapacity;
/** Decide whether the model-free fuse may act for this host trigger. */
export declare function shouldRunEmergencyFallback(trigger: 'pressure' | 'context-overflow', projectedTokens: number | null, contextWindow: number, config: AdaptiveGovernorConfig, outputReserve?: number): boolean;
/**
 * Translate the governor policy into kernel inputs.
 *
 * Growth-only nudges are disabled by setting their adaptive threshold to the
 * whole effective input budget. The kernel's over-limit and emergency paths
 * remain intact and render the ordinary ARC range table/tool guidance.
 */
export declare function governedKernelInput(input: KernelConfigInput, config: AdaptiveGovernorConfig, outputReserve?: number): KernelConfigInput;