/**
 * OAI-mem-citation parser and formatter (issue #379).
 *
 * Mirrors the citation block format used by Codex's `citations.rs` so that
 * Remnic recall responses produce compatible citation blocks. The model
 * appends these blocks to its final reply, and downstream hooks parse them
 * to increment memory usage tracking.
 *
 * Block format:
 *
 *   <oai-mem-citation>
 *   <citation_entries>
 *   path/to/file.md:1-5|note=[short explanation]
 *   </citation_entries>
 *   <rollout_ids>
 *   rollout-abc123
 *   </rollout_ids>
 *   </oai-mem-citation>
 */
/** A single citation entry referencing a memory file and line range. */
interface CitationEntry {
    path: string;
    lineStart: number;
    lineEnd: number;
    note: string;
}
/** Parsed citation block containing entries and rollout/thread IDs. */
interface CitationBlock {
    entries: CitationEntry[];
    rolloutIds: string[];
}
/** Metadata attached to a recall result for citation guidance. */
interface CitationMetadata {
    memoryId: string;
    path: string;
    lineStart: number;
    lineEnd: number;
    rolloutId?: string;
    noteDefault: string;
}
/**
 * Parse an `<oai-mem-citation>` block from arbitrary text.
 *
 * Returns `null` when no valid block is found. Malformed entry lines are
 * silently skipped; only valid lines contribute to the result. Rollout IDs
 * are deduped while preserving insertion order.
 */
declare function parseOaiMemCitation(text: string): CitationBlock | null;
/**
 * Replace newline characters (\n, \r) with spaces so that note values can be
 * safely embedded in a single citation entry line without corrupting the
 * line-based parser (`parseEntryLine` splits on `\n`).
 */
declare function sanitizeNoteForCitation(note: string): string;
/**
 * Format a `CitationBlock` into the canonical `<oai-mem-citation>` XML block.
 */
declare function formatOaiMemCitation(block: CitationBlock): string;
/**
 * Build the citation guidance text appended to recall responses so that the
 * model knows how to emit a citation block in its reply.
 *
 * Returns an empty string when `citations` is empty (no guidance needed).
 */
declare function buildCitationGuidance(citations: CitationMetadata[]): string;

export { type CitationBlock, type CitationEntry, type CitationMetadata, buildCitationGuidance, formatOaiMemCitation, parseOaiMemCitation, sanitizeNoteForCitation };
