/**
 * Smart agent dispatcher.
 *
 * Routes a free-form task description to the best agent in the catalog using a
 * two-stage strategy:
 *
 *   1. Heuristic — keyword/phrase scoring against each agent's `capability`
 *      metadata. Deterministic, instant, no provider call. Multi-word phrases
 *      score higher than single words (they're more specific signals).
 *
 *   2. LLM fallback — when the heuristic is ambiguous (confidence below the
 *      threshold, or no keyword hit at all) an injected `classifier` resolves
 *      the tie. The classifier is provider-agnostic: callers wire it to any
 *      `complete(prompt) => text` function via `makeLLMClassifier`, so core
 *      stays free of provider dependencies and the path is unit-testable.
 *
 * If neither stage yields a confident pick, the dispatcher falls back to the
 * `executor` generalist rather than failing.
 */
import { type AgentDefinition } from './agents/index.js';
/** Default agent used when nothing else matches — the generalist builder. */
export declare const DEFAULT_DISPATCH_ROLE = "executor";
export interface DispatchCandidate {
    role: string;
    name: string;
    score: number;
    /** Capability keywords that matched the task text. */
    matched: string[];
}
export type DispatchMethod = 'heuristic' | 'llm' | 'fallback';
export interface DispatchResult {
    role: string;
    definition: AgentDefinition;
    /** 0..1 — heuristic margin, or 1 when an LLM made a definite choice. */
    confidence: number;
    method: DispatchMethod;
    /** Human-readable explanation of why this agent was chosen. */
    reason: string;
    /** Runner-up candidates (top heuristic scorers), best-first. */
    alternatives: DispatchCandidate[];
}
/**
 * Provider-agnostic classifier seam. Given the task and the candidate agents
 * (role + summary), return the chosen role (and optional reason), or null to
 * decline. Wire via `makeLLMClassifier`.
 */
export type DispatchClassifier = (task: string, candidates: {
    role: string;
    name: string;
    summary: string;
}[]) => Promise<{
    role: string;
    reason?: string | undefined;
} | null>;
export interface DispatchOptions {
    /** Optional LLM fallback for ambiguous tasks. */
    classifier?: DispatchClassifier | undefined;
    /** Heuristic confidence below this triggers the classifier. Default 0.4. */
    confidenceThreshold?: number | undefined;
    /** How many top candidates to offer the classifier. Default 6. */
    maxCandidates?: number | undefined;
    /** Override the catalog (testing). Defaults to the full `AGENT_CATALOG`. */
    catalog?: Record<string, AgentDefinition> | undefined;
}
/**
 * Score every agent against the task. A keyword hit adds 1 point; a multi-word
 * keyword phrase adds points equal to its word count (more specific = stronger
 * signal). Returns candidates sorted best-first, zero-score agents dropped.
 */
export declare function scoreAgents(task: string, catalog?: Record<string, AgentDefinition>): DispatchCandidate[];
/**
 * Route a task to the best agent. Async because the LLM fallback may run; the
 * pure-heuristic path resolves without awaiting anything.
 */
export declare function dispatchAgent(task: string, opts?: DispatchOptions): Promise<DispatchResult>;
/**
 * Build a `DispatchClassifier` from a minimal `complete(prompt) => text`
 * function. The caller supplies the provider call; this owns the prompt and
 * the parsing. Keeps `dispatcher` free of any provider import.
 */
export declare function makeLLMClassifier(complete: (prompt: string) => Promise<string>): DispatchClassifier;
//# sourceMappingURL=dispatcher.d.ts.map