/**
 * Agent discovery and configuration.
 *
 * Discovers agent definitions from package, compatible project, and user locations.
 * Precedence: package > project .pi/agents > project .agents > user global dirs > builtin.
 */
import { type TeammateTaskType } from "../shared/task-types.ts";
import { type TeammateThinkingLevel } from "../shared/thinking.ts";
type SystemPromptMode = "append" | "replace";
export type AgentSource = "builtin" | "package" | "user" | "project";
export declare const BUILTIN_AGENT_NAMES: readonly ["general", "explorer", "planner", "analyst", "research", "verifier", "workflow"];
export type BuiltinAgentName = (typeof BUILTIN_AGENT_NAMES)[number];
export declare const PUBLIC_BUILTIN_AGENT_NAMES: readonly ["general", "explorer", "planner", "analyst", "research", "verifier", "workflow"];
export interface AgentConfig {
    name: string;
    description: string;
    tools?: string[];
    model?: string;
    fallbackModels?: string[];
    taskType?: TeammateTaskType;
    thinking?: TeammateThinkingLevel;
    systemPromptMode: SystemPromptMode;
    inheritProjectContext: boolean;
    inheritSkills: boolean;
    defaultContext?: "fresh" | "fork";
    systemPrompt: string;
    source: AgentSource;
    filePath: string;
}
export interface AgentSummary {
    name: string;
    description: string;
    source: AgentSource;
}
export interface AgentDefinitionReference {
    source: AgentSource;
    filePath: string;
}
export interface AgentShadowDiagnostic {
    name: string;
    reason: "shadowed" | "reserved-builtin";
    winner: AgentDefinitionReference;
    candidate: AgentDefinitionReference;
}
export interface AgentDiscoverySnapshot {
    agents: AgentConfig[];
    diagnostics: AgentShadowDiagnostic[];
}
export interface AgentDiscoveryOptions {
    includeDiagnostics: true;
    homeDir?: string;
}
export interface AgentCatalogSnapshot {
    signature: string;
    systemPrompt: string;
}
export declare function isBuiltinAgentName(name: string): name is BuiltinAgentName;
/**
 * Discover all agent definitions, merged by priority:
 * package > project > user > builtin (name collisions: higher priority wins).
 */
export declare function discoverAgents(cwd: string, options: AgentDiscoveryOptions): AgentDiscoverySnapshot;
export declare function discoverAgents(cwd: string, homeDir?: string): AgentConfig[];
/** Resolve a single agent by name, optionally from an existing discovery snapshot. */
export declare function resolveAgent(discovery: AgentDiscoverySnapshot, agentName: string): AgentConfig | undefined;
export declare function resolveAgent(cwd: string, agentName: string): AgentConfig | undefined;
/** Return resolved role metadata without exposing the role prompt body. */
export declare function listAgentSummaries(discovery: AgentDiscoverySnapshot): AgentSummary[];
export declare function listAgentSummaries(cwd: string, homeDir?: string): AgentSummary[];
/** Format diagnostics only for the exact role selected for dispatch. */
export declare function formatAgentShadowWarning(discovery: AgentDiscoverySnapshot, agentName: string): string | undefined;
/** Format a compact, deterministic role catalog for teammate tool metadata. */
export declare function formatAgentCatalog(cwd: string, maxRoles?: number, maxDescriptionLength?: number): string;
/**
 * Hit/miss counters for the role catalog cache, reset by
 * {@link invalidateAgentCatalogCache}. Observability only; never consulted
 * for cache decisions.
 */
export declare const agentCatalogCacheStats: {
    hits: number;
    misses: number;
};
/**
 * Drop every cached catalog snapshot. Called when the extension re-registers
 * (reload); cwd changes and role additions/edits invalidate themselves via the
 * cache key and manifest signature respectively.
 */
export declare function invalidateAgentCatalogCache(): void;
/** Build the compact role directory appended to the active parent prompt. */
export declare function createAgentCatalogSnapshot(cwd: string, maxDescriptionLength?: number): AgentCatalogSnapshot;
/** Replace an existing role directory or append a fresh one to the prompt. */
export declare function appendAgentCatalog(systemPrompt: string, cwd: string): string;
export {};