import type { AgentMessage } from "@earendil-works/pi-agent-core"; import type { Message, Model } from "@earendil-works/pi-ai"; export type ContextCategory = "instructions" | "tool_definitions" | "conversation" | "tool_results" | "summaries" | "other"; export type ContextBreakdownBasis = "current_projection" | "last_request"; export interface ContextBreakdownOptions { basis?: ContextBreakdownBasis; category?: ContextCategory; } export interface ContextBreakdownNode { id: string; category: ContextCategory; label: string; estimatedTokens: number | null; attribution: "structured" | "role" | "opaque" | "unknown"; sourceKind: "builtin" | "sdk" | "extension" | "session" | "unknown"; children: ContextBreakdownNode[]; omittedChildren: number; } export type ContextBreakdownReason = "baseline_only" | "baseline_unavailable" | "pending_request_changes" | "transforms_unobserved" | "no_request_observation" | "stale_request" | "provider_payload_opaque" | "provider_serialization_unaccounted" | "system_history_unaccounted" | "nontext_approximate" | "nontext_unknown" | "request_usage_unaligned" | "in_flight_content_excluded" | "capacity_unavailable" | "session_unavailable" | "invalid_numeric_value" | "output_truncated"; export interface ContextBreakdownSnapshot { version: 1; status: "available" | "partial" | "unavailable"; sessionId: string | null; epoch: string; revision: number; capturedAt: number; basis: ContextBreakdownBasis; freshness: "current" | "stale" | "unavailable"; selectedModel: { provider: string; id: string; api: string; } | null; effectiveModel: { provider: string; id: string; api: string; } | null; capacityTokens: number | null; authoritativeUsage: { tokens: number | null; contextWindow: number; percent: number | null; } | null; estimateMethod: "chars4-components-v1"; coverage: "logical" | "partial" | "unavailable"; estimatedAllocationTokens: number | null; discrepancyTokens: number | null; grid: { basis: "estimated_allocation_vs_capacity"; remainder: "unknown"; overCapacity: boolean | null; }; categories: ContextBreakdownNode[]; omittedNodes: number; reasons: ContextBreakdownReason[]; } export declare const CONTEXT_CATEGORIES: readonly ContextCategory[]; export declare function validateContextBreakdownOptions(options?: ContextBreakdownOptions): void; /** The SDK and pure projection use the same image policy, without invoking user hooks. */ export declare function convertContextMessages(messages: AgentMessage[], blockImages: boolean): Message[]; export declare function contextMessageKinds(messages: AgentMessage[]): string[]; /** One-way relevant-state fingerprint; raw content is never retained by the inspector. */ export declare function contextStateSignature(value: unknown): string; export interface ContextBreakdownEvidence { sessionId: string; selectedModel?: Model; effectiveModel?: Model; capacity?: number; usage?: ContextBreakdownSnapshot["authoritativeUsage"]; messages: Message[]; kinds?: string[]; reasons?: ContextBreakdownReason[]; } export declare function createContextBreakdown(evidence: ContextBreakdownEvidence, identity: { epoch: string; revision: number; basis: ContextBreakdownBasis; capturedAt?: number; }): ContextBreakdownSnapshot; export declare function unavailableContextBreakdown(epoch: string, revision: number, basis: ContextBreakdownBasis, reason: "session_unavailable" | "no_request_observation"): ContextBreakdownSnapshot; interface RequestToken { epoch: string; generation: number; revision: number; } /** Runtime-only state shared by this SDK Agent and its session. Never owns raw request bodies. */ export declare class ContextBreakdownObservation { epoch: `${string}-${string}-${string}-${string}-${string}`; revision: number; private generation; private signature; private binding; private sessionId; private observed; private prepared; private converted; reset(): void; reconcile(signature: string, sessionId: string, binding: object | null): void; touch(): void; begin(): RequestToken; private valid; prepare(token: RequestToken, messages: AgentMessage[]): void; transform(messages: AgentMessage[], transform: () => Promise): Promise; convert(messages: AgentMessage[], converted: Message[]): void; capture(messages: Message[], evidence: Omit): void; read(category?: ContextCategory): ContextBreakdownSnapshot; } /** Bounded plain metadata report shared by every presentation/transport. */ export declare function formatContextBreakdown(snapshot: ContextBreakdownSnapshot, options?: { category?: ContextCategory; }): string; export {};