Controllers and policies

export interface ReflectionPolicyOptions extends ControlOptions {
    id?: string;
    /** Host-authored acceptance criteria, not retrieved instructions. */
    criteria: string;
    /** Maximum critic output tokens; the host binding must allow maxTokens. Default: 1024. */
    maxTokens?: number;
}

export interface SummaryContextPolicyOptions extends ControlOptions {
    id?: string;
    /** Request token estimate including instructions, retained turns and summary. */
    maxContextTokens: number;
    /** Latest complete turn groups kept unchanged, including the live turn. Default: 1. */
    keepRecentTurns?: number;
    /** Maximum summary output tokens; the host binding must allow maxTokens. Default: 1024. */
    summaryMaxTokens?: number;
}

/** A budgeted critic. Revisions and effect permissions remain owned by HarnessRuntime. */
export declare function reflectionPolicy(options: ReflectionPolicyOptions): CompletionPolicy;

/** Summarize removable historical turns, preserving host instructions and the latest whole turns. */
export declare function summaryContextPolicy(options: SummaryContextPolicyOptions): ContextPolicy;

export type CompletionDecision = {
    action: "accept";
    reason: string;
    evidence?: readonly string[];
} | {
    action: "revise";
    reason: string;
    instruction: string;
    evidence?: readonly string[];
} | {
    action: "await_input" | "stop";
    reason: string;
    evidence?: readonly string[];
};

export interface CompletionPolicy {
    id: string;
    evaluate: (response: {
        text: string;
        structured?: unknown;
        revision: number;
    }, ctx: RunContext) => Promise<CompletionDecision>;
}

export interface ContextPolicy {
    id: string;
    project: (input: {
        history: readonly ChatMessage[];
        entries: readonly HarnessContextEntry[];
    }, ctx: RunContext) => Promise<ContextProjection>;
}

export interface ContextProjection {
    messages: ChatMessage[];
    provenance: readonly {
        sourceId: string;
        included: boolean;
        reason?: string;
    }[];
}

export interface ModelRoleBinding {
    provider: import("@agentium/core").ModelProvider;
    /** Explicit allowlist of ModelConfig keys supported by this binding. */
    options?: readonly (keyof ModelConfig)[];
}

export interface StepController {
    id: string;
    prepareRun?: (ctx: RunContext) => Promise<StepOverrides | undefined>;
    prepareStep?: (step: {
        index: number;
        tools: readonly ToolDefinition[];
    }, ctx: RunContext) => Promise<StepOverrides | undefined>;
}

export interface StepOverrides {
    activeToolIds?: readonly string[];
    modelRole?: string;
    options?: ModelConfig;
    contextPolicy?: ContextPolicy;
    stop?: {
        reason: string;
    };
}

interface ControlOptions {
    /** Explicit role in HarnessRuntime.models and grants.modelRoles. */
    modelRole: string;
    /** Maximum serialized source bytes sent to the policy model. Default: 65536. */
    maxInputBytes?: number;
}