import { type ExecutorKind } from "./executors.js";
export declare const DEFAULT_SESSION_SHORT_REF_LENGTH = 10;
export interface SessionSelectorCandidate {
    /** Complete, authoritative conversation/session id. */
    id: string;
    /**
     * Optional operation target returned after this candidate is selected.
     * Matching, short references, and candidate details remain anchored to
     * `id`, allowing a physical terminal to route an operation to its current
     * managed turn without changing the terminal's public selector identity.
     */
    targetId?: string;
    agent: ExecutorKind;
    /**
     * Whether the caller can perform its current operation on this target.
     *
     * Actionability is intentionally supplied by the caller because it differs
     * between operations (for example, a native session can be described but
     * cannot receive terminal input).
     */
    actionable: boolean;
    /**
     * Whether this candidate participates in omitted and semantic selector
     * resolution (`only`, `latest`, an agent name, or `agent:latest`).
     *
     * Set this to false for explicitly addressable history, such as an older
     * managed turn attached to a physical terminal. Complete ids and short refs
     * still resolve the candidate when `actionable` is true. Omission preserves
     * the previous behavior and allows the candidate into default selection.
     */
    defaultActionable?: boolean;
    /**
     * Caller-supplied recency. It must not be derived from the current clock in
     * this resolver. `latest` fails closed when recency is missing or tied.
     */
    updatedAtMs?: number;
    source?: string;
    status?: string;
    workspace?: string;
    label?: string;
}
export interface SessionSelectorCandidateDetail {
    id: string;
    shortRef: string;
    agent: ExecutorKind;
    actionable: boolean;
    defaultActionable?: boolean;
    updatedAtMs?: number;
    source?: string;
    status?: string;
    workspace?: string;
    label?: string;
}
export type SessionSelectorMatchKind = "full_id" | "short_ref" | "implicit_only" | "only" | "latest" | "agent" | "agent_latest";
export interface SessionSelectorResolution<T extends SessionSelectorCandidate> {
    candidate: T;
    id: string;
    shortRef: string;
    selector?: string;
    matchedBy: SessionSelectorMatchKind;
}
export type SessionSelectorErrorCode = "ambiguous" | "no_actionable_targets" | "not_actionable" | "not_found";
export declare class SessionSelectorError extends Error {
    readonly code: SessionSelectorErrorCode;
    readonly selector?: string;
    readonly candidates: readonly SessionSelectorCandidateDetail[];
    constructor(options: {
        code: SessionSelectorErrorCode;
        message: string;
        selector?: string;
        candidates?: readonly SessionSelectorCandidateDetail[];
    });
}
export interface SessionSelectorOptions {
    /** Used only to make error messages operation-specific, such as "send". */
    operation?: string;
    /**
     * Hash characters after `@`. Production callers should keep the default.
     * Shorter values are supported for deterministic collision testing.
     */
    shortRefLength?: number;
}
/**
 * Produce a stable, opaque reference that does not depend on list order or on
 * the other currently visible sessions.
 */
export declare function sessionShortRef(id: string, length?: number): string;
/**
 * Return display-ready candidate details in a deterministic order.
 */
export declare function sessionSelectorCandidateDetails(candidates: readonly SessionSelectorCandidate[], options?: Pick<SessionSelectorOptions, "shortRefLength">): SessionSelectorCandidateDetail[];
/**
 * Resolve a user-facing selector to one authoritative id.
 *
 * This function only resolves identity. The caller must still revalidate any
 * PID, tmux pane/socket, native session id, or process identity immediately
 * before performing a side effect.
 */
export declare function resolveSessionSelector<T extends SessionSelectorCandidate>(selector: string | null | undefined, candidates: readonly T[], options?: SessionSelectorOptions): SessionSelectorResolution<T>;