import type { AgentMessage } from "@caupulican/pi-agent-core/types";
import type { CurationTelemetrySnapshot } from "./brain-curator.ts";
/**
 * Context composition dashboard (user-facing): decomposes EVERYTHING that rides along on every
 * request — system prompt, active tool schemas, extension contributions, injected blocks
 * (memory recall pages, evidence blocks), and the session messages themselves (raw vs. GC-packed
 * vs. policy-stubbed) — so a user integrating their own tools/extensions can see exactly what
 * each addition costs per request and where cleaning is (or is not) working.
 *
 * Honesty contract: everything here is an ESTIMATE (chars/4) EXCEPT `providerReportedTokens`,
 * which is what the provider actually billed. The dashboard always shows both and the delta —
 * the delta is the measure of how much the estimates can be trusted, never hidden.
 *
 * Known exclusions (named, not hidden): extension `context` handlers may rewrite messages at
 * send time in ways this view cannot see. The memory evidence block and enforcement stubbing
 * are ALSO send-time-only, but those are modeled explicitly via `adjustments`.
 */
export interface ToolCompositionRow {
    name: string;
    /** Estimated tokens for the tool's name+description+schema as sent to the provider. */
    schemaTokens: number;
    source: "built-in" | "extension";
}
export interface ExtensionCompositionRow {
    name: string;
    path: string;
    toolCount: number;
    commandCount: number;
    /** Estimated schema tokens of this extension's ACTIVE tools (its per-request cost). */
    activeToolSchemaTokens: number;
}
export interface MessageClassRow {
    label: string;
    count: number;
    tokens: number;
}
export interface ContextCompositionReport {
    /** Estimated tokens of the system prompt sent on every request. */
    systemPromptTokens: number;
    systemPromptChars: number;
    /** Estimated tokens of ALL active tool schemas sent on every request. */
    toolSchemaTokens: number;
    tools: ToolCompositionRow[];
    extensions: ExtensionCompositionRow[];
    /** Session message classes (raw/user/assistant/stubs/recall pages), heaviest first. */
    messageClasses: MessageClassRow[];
    messageTokens: number;
    messageCount: number;
    /** Estimated total sent per request: system prompt + tool schemas + messages. */
    estimatedRequestTokens: number;
    /** What the provider actually reported for the current context, when known. */
    providerReportedTokens: number | null;
    contextWindow: number | null;
    gc: {
        packedCount: number;
        savedTokens: number;
    } | null;
    enforcement: {
        enforcedCount: number;
        advisoryEvictions: number;
    } | null;
    curation: {
        enabled: boolean;
        telemetry: CurationTelemetrySnapshot;
        lastSkipReason?: string;
    } | null;
    /** Background/side-channel spend that does NOT ride in this context but bills the account. */
    spawned: {
        cost: number;
        reports: number;
    } | null;
    /** Send-time-only deltas folded into estimatedRequestTokens: +evidence block, -policy stubs. */
    adjustments: {
        memoryEvidenceTokens: number;
        enforcementSavedTokens: number;
    };
    /** Actionable, bounded observations derived from the numbers above. */
    observations: string[];
}
export interface BuildContextCompositionInput {
    systemPrompt: string;
    tools: Array<{
        name: string;
        description?: string;
        providerDescription?: string;
        parameters?: unknown;
        source?: "built-in" | "extension";
    }>;
    extensions: Array<{
        name: string;
        path: string;
        toolNames: string[];
        commandCount: number;
    }>;
    messages: AgentMessage[];
    providerReportedTokens: number | null;
    contextWindow: number | null;
    gc?: {
        packedCount: number;
        savedTokens: number;
    };
    enforcement?: {
        enforcedCount: number;
        advisoryEvictions: number;
    };
    curation?: {
        enabled: boolean;
        telemetry: CurationTelemetrySnapshot;
        lastSkipReason?: string;
    };
    spawned?: {
        cost: number;
        reports: number;
    };
    adjustments?: {
        memoryEvidenceTokens: number;
        enforcementSavedTokens: number;
    };
    /** Pre-formed warnings from other subsystems (e.g. profile-withheld context files). */
    extraObservations?: string[];
}
export declare function buildContextCompositionReport(input: BuildContextCompositionInput): ContextCompositionReport;
/** Bounded plain-text dashboard (interactive `/context` command and tests). */
export declare function formatContextCompositionDashboard(report: ContextCompositionReport, maxToolRows?: number): string;
//# sourceMappingURL=context-composition.d.ts.map