/**
 * Agent file parser for MCP planning tools.
 *
 * Agent files use YAML frontmatter as the single source of truth for task state.
 * This module provides functions to parse, update, and query agent files.
 *
 * Task ID Format: `<plan-folder>#<agent-number>` (e.g., "0022-datagrid-stories#000")
 */
import type { ScoringWeights } from './config.js';
/**
 * Agent file frontmatter interface.
 * This is the authoritative source of truth for agent/task state.
 */
export interface AgentFrontmatter {
    status: 'GAP' | 'WIP' | 'PASS' | 'BLOCKED';
    persona: 'coder' | 'reviewer' | 'pm' | 'customer';
    dependencies: string[];
    blocks: string[];
    files: string[] | {
        path: string;
        action?: string;
        repo?: string;
    }[];
    title?: string;
    tags?: string[];
    aliases?: string[];
    created?: string;
    updated?: string;
    scoring?: {
        bias?: number;
        weights?: Partial<ScoringWeights>;
    };
    depends_on?: string[] | string;
}
/**
 * Parsed agent file with frontmatter and metadata.
 */
export interface ParsedAgentFile {
    /** Task ID: planFolder#agentNumber */
    taskId: string;
    /** Plan folder name (e.g., "0022-datagrid-stories") */
    planFolder: string;
    /** Agent number (e.g., "000") */
    agentNumber: string;
    /** Full path to the agent file */
    path: string;
    /** Parsed frontmatter */
    frontmatter: AgentFrontmatter;
    /** Content after frontmatter */
    content: string;
    /** File modification time (for stale detection) */
    mtime: Date;
    /** Title extracted from first # heading */
    title: string;
}
/**
 * Extract agent number from filename.
 *
 * @example
 * extractAgentNumber("000_agent_sticky_header.agent.md") // "000"
 * extractAgentNumber("001_agent_navigation.agent.md") // "001"
 * extractAgentNumber("signalbadge.agent.md") // null (no number prefix)
 *
 * @param filename - Agent filename (not full path)
 * @returns Agent number or null if not found
 */
export declare function extractAgentNumber(filename: string): string | null;
/**
 * Extract plan folder from agent file path.
 *
 * @example
 * extractPlanFolder("/path/to/0022-datagrid-stories/agents/000_agent.agent.md")
 * // "0022-datagrid-stories"
 *
 * @param path - Full path to agent file
 * @returns Plan folder name or null if not found
 */
export declare function extractPlanFolder(path: string): string | null;
/**
 * Build task ID from plan folder and agent number.
 *
 * @example
 * buildTaskId("0022-datagrid-stories", "000") // "0022-datagrid-stories#000"
 *
 * @param planFolder - Plan folder name
 * @param agentNumber - Agent number
 * @returns Task ID in format planFolder#agentNumber
 */
export declare function buildTaskId(planFolder: string, agentNumber: string): string;
/**
 * Parse task ID to extract plan folder and agent number.
 *
 * @example
 * parseTaskId("0022-datagrid-stories#000")
 * // { planFolder: "0022-datagrid-stories", agentNumber: "000" }
 *
 * @param taskId - Task ID
 * @returns Parsed components or null if invalid format
 */
export declare function parseTaskId(taskId: string): {
    planFolder: string;
    agentNumber: string;
} | null;
/**
 * Parse an agent file and extract frontmatter and metadata.
 *
 * @param path - Full path to agent file
 * @param content - File content
 * @returns Parsed agent file or null if not a valid agent file
 */
export declare function parseAgentFile(path: string, content: string): ParsedAgentFile | null;
/**
 * Read and parse an agent file from disk.
 *
 * @param path - Full path to agent file
 * @returns Parsed agent file or null if not found or invalid
 */
export declare function readAgentFile(path: string): ParsedAgentFile | null;
/**
 * Update agent file frontmatter on disk.
 *
 * @param path - Full path to agent file
 * @param updates - Partial frontmatter updates
 * @returns Updated parsed agent file or null on error
 */
export declare function updateAgentFrontmatter(path: string, updates: Partial<AgentFrontmatter>): ParsedAgentFile | null;
/**
 * Add frontmatter to a legacy agent file (migration helper).
 * Extracts state from content and adds proper YAML frontmatter.
 *
 * @param path - Full path to agent file
 * @returns Updated parsed agent file or null on error
 */
export declare function migrateAgentFile(path: string): ParsedAgentFile | null;
/**
 * Check if an agent is stale (WIP status but mtime > threshold).
 *
 * @param agent - Parsed agent file
 * @param thresholdMinutes - Stale threshold in minutes (default 10)
 * @returns true if agent is stale
 */
export declare function isAgentStale(agent: ParsedAgentFile, thresholdMinutes?: number): boolean;
/**
 * Find agent file path by task ID.
 *
 * @param plansPath - Base path to plans directory
 * @param taskId - Task ID in format planFolder#agentNumber
 * @returns Full path to agent file or null if not found
 */
export declare function findAgentFilePath(plansPath: string, taskId: string): string | null;
/**
 * Resolve a dependency reference to a full task ID.
 * Handles both agent numbers ("000") and full task IDs ("0022-plan#000").
 *
 * @param dep - Dependency reference
 * @param currentPlanFolder - Current plan folder for relative references
 * @returns Full task ID or null if invalid
 */
export declare function resolveDependency(dep: string, currentPlanFolder: string): string | null;
//# sourceMappingURL=agent-parser.d.ts.map