/**
 * Host-agent enrichment for the POC v2 envelope.
 *
 * After the engine produces measured findings (per-pattern $/mo,
 * growth, incident clusters, action recommendations), this module
 * asks the MCP host's LLM to contribute operational context the
 * engine cannot see:
 *
 *   1. Causal hypothesis — was there a deploy/config change that
 *      explains a GROWING or NEW pattern?
 *   2. Dependency safety — are there alerts/dashboards/queries that
 *      reference a pattern we recommend muting (would the mute
 *      silence something important)?
 *   3. Code-level root-cause refinement — given the engine's
 *      `bug_hypothesis`, what's the specific code change the agent
 *      can suggest using its access to source / docs?
 *   4. Prioritization — given the customer's context, which of the
 *      top-N findings should ship this sprint vs. backlog?
 *
 * The host agent has tools we don't (kubectl, source code, helm,
 * Grafana, PagerDuty, the customer's other MCPs). We have data it
 * doesn't (14d measured patterns, deterministic fingerprints, real
 * costs). Together the report is richer than either alone.
 *
 * Honest constraints:
 *   - Token budget capped per session (default 8k output tokens)
 *   - Graceful no-op when host doesn't advertise the `sampling`
 *     capability — common for cron / headless / non-Claude hosts
 *   - Single round-trip with a structured-JSON prompt; if parsing
 *     fails we attach the raw text as `raw_response` and move on
 *   - Auditable: every contribution carries a `tools_inspected` list
 *     so the customer sees what the agent says it looked at
 */
import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import type { PocEnvelopeV2, PatternOutput } from './poc-envelope-v2.js';
export interface AgentContribution {
    /**
     * Which loop produced this contribution. Multiple loops may apply
     * to the same pattern (e.g., a GROWING pattern flagged for `mute`
     * gets both `operational_context` and `dependency_safety`).
     */
    loop: 'operational_context' | 'dependency_safety' | 'code_fix_refinement' | 'prioritization';
    /** Top-N pattern indices this contribution applies to. */
    target_pattern_indices: number[];
    /**
     * What the agent says it inspected: ['kubectl_events', 'grafana_dashboards',
     * 'source_code', 'helm_release', 'pagerduty_rules', etc.]. Surfaces the
     * audit trail to the customer — if the agent claims to have checked
     * something, the customer can verify.
     */
    tools_inspected: string[];
    /**
     * 1-3 sentence findings from the agent. Quoted verbatim by the
     * customer's report writer.
     */
    findings: string[];
    /** `high` / `medium` / `low` — how strongly the agent stands behind the contribution. */
    confidence: 'high' | 'medium' | 'low';
    /**
     * Free-form raw response when structured parsing failed. Lets the
     * customer's agent recover the content even when the JSON contract
     * didn't survive.
     */
    raw_response?: string;
}
export interface AgentEnrichmentResult {
    contributions: AgentContribution[];
    metadata: {
        host_capability: 'sampling_supported' | 'sampling_unsupported' | 'host_unavailable';
        tokens_spent: number;
        calls_attempted: number;
        calls_succeeded: number;
        skipped_reason?: string;
    };
}
export interface EnrichOptions {
    /** MCP server instance. Sampling is server-side; without it we no-op. */
    server?: McpServer;
    /** Per-session output token cap. Default 8000. */
    maxTokensTotal?: number;
    /** Per-call timeout. Default 60s — agent enrichment may inspect external tools. */
    timeoutMs?: number;
    /**
     * Cap on top-N patterns considered for enrichment. Default 10 —
     * agent attention is finite; the head of the cost distribution is
     * what matters anyway.
     */
    topN?: number;
}
/**
 * Run the enrichment loops against the v2 envelope. Returns an
 * AgentEnrichmentResult that the caller attaches to the envelope's
 * `output.agent_enrichment` field. Never throws — failures degrade
 * to empty contributions with an `errorNote`-equivalent metadata field.
 */
export declare function enrichWithHostAgent(envelope: PocEnvelopeV2, opts?: EnrichOptions): Promise<AgentEnrichmentResult>;
/**
 * Exposed for testing / dry-runs. The standalone POC runner uses this
 * to print the per-finding errand prompt for a real envelope without
 * actually round-tripping to an MCP host.
 */
export declare function _buildEnrichmentPromptForTest(envelope: PocEnvelopeV2, patterns: PatternOutput[]): string;