Runtime utilities

/**
 * Assert a URL's host is in the allowlist, throwing `PathSecurityError` if not.
 */
export declare function assertHostAllowed(url: string, allowedHosts?: string[]): void;

/** Resolve links, including the nearest existing parent of a new file.
 * This prevents static symlink escapes, not hostile concurrent filesystem replacement.
 */
export declare function canonicalSafeJoin(baseDir: string, relPath: string, allowMissing?: boolean): Promise<string>;

/**
 * Count total tokens across an array of messages.
 */
export declare function countMessagesTokens(messages: ChatMessage[], modelId?: string): number;

/**
 * Count tokens for a ChatMessage (content + per-message overhead).
 */
export declare function countMessageTokens(msg: ChatMessage, modelId?: string): number;

/**
 * Count tokens in a text string.
 *
 * When `gpt-tokenizer` is installed, returns exact BPE token count.
 * Otherwise, uses a model-family-aware character ratio that is
 * calibrated to slightly over-estimate (safe for budget enforcement).
 *
 * @param text - The text to count tokens for
 * @param modelId - Optional model identifier for calibrated fallback ratio
 */
export declare function countTokens(text: string, modelId?: string): number;

/**
 * Returns true when a real tokenizer is loaded (not using heuristic).
 * Useful for logging accuracy warnings.
 */
export declare function hasExactTokenizer(): boolean;

/**
 * Returns true when a hostname (or full URL) is allowed by an allowlist.
 *
 * Allowlist entries match the hostname exactly OR as a suffix (so `*.example.com`
 * is achieved by listing `example.com` and the matcher will accept any sub-domain).
 *
 * When `allowedHosts` is `undefined` or empty, returns true (no restriction).
 */
export declare function isHostAllowed(urlOrHost: string, allowedHosts?: string[]): boolean;

/**
 * Thrown when a path traversal, symlink escape, or other path-safety violation is detected.
 */
export declare class PathSecurityError extends Error {
    constructor(message: string);
}

export interface RetryConfig {
    maxRetries: number;
    initialDelayMs: number;
    maxDelayMs: number;
    retryableErrors?: (error: unknown) => boolean;
}

/**
 * Join a base directory with a relative path, ensuring the result is contained
 * within the base directory. Detects classic traversal attempts (`../../etc/passwd`),
 * absolute-path escapes, and embedded control characters / null bytes that some
 * filesystems treat specially.
 *
 * Does NOT resolve symlinks - callers that need symlink-aware safety should use
 * `fs.realpath` after this check.
 */
export declare function safeJoin(baseDir: string, relPath: string): string;

export declare function withRetry<T>(fn: () => Promise<T>, config?: Partial<RetryConfig>): Promise<T>;