/**
 * Workspace @mention support: file and directory candidates from the
 * `fileReferences` service (dsh-file-reference-local), session candidates
 * from the opt-in `sessionReferenceResolver` service, and submission
 * preparation through its `prepare()` API. Picked session mentions land as
 * canonical `@[label](dsh-session:…)` tokens; on submit the text is parsed
 * back into readable `@label` text plus structured references, snapshots are
 * injected via `agent.inject()` before the readable message wakes the driver
 * (`followup`, which queues the next turn whether or not one is running) —
 * exactly the upstream README's wiring. Steering the current turn is a
 * deliberate user action through the `/queue` panel, never an implicit
 * consequence of submitting while busy.
 *
 * File discovery lives entirely in the Harness service (per-agent bounded
 * index, `@dir/` listing, symlink guards, tool/result invalidation); this
 * module only maps candidates to menu rows and never re-implements scanning.
 * The service is agent-scoped (the agent supplies the session cwd and the
 * cache key), so before the first session creates an agent the SAME official
 * search class runs against the launch cwd — @ file completion works on a
 * bare launch, model- and session-independent, and the agent-scoped service
 * takes over once a session exists.
 *
 * @module @deepseek-ai/dsh-code/mentions
 */
import type { Context } from '@deepseek-ai/cordis';
import type { Agent } from '@deepseek-ai/dsh-agent';
import type { UserMessage } from '@deepseek-ai/dsh-session';
import { parseSessionReferenceText, type SessionReferenceCandidate, type SessionReferenceInput } from '@deepseek-ai/dsh-session-reference';
/** Parsed submission text: readable text plus structured references. */
type ParsedSessionReferenceText = ReturnType<typeof parseSessionReferenceText>;
/** One merged menu candidate (files and sessions, already ranked). */
export interface MentionCandidate {
    /** Text inserted after the `@` (directories carry a trailing slash). */
    label: string;
    /** Human-readable origin shown beside the label. */
    description: string;
    /** Origin kind for icon/coloring decisions. */
    kind: 'file' | 'directory' | 'session';
    /** Absolute path for file candidates; never rendered or persisted directly. */
    path?: string;
}
/** Prepared submission: readable content plus optional injected context. */
export interface PreparedMention {
    /** Readable text with mention tokens normalized to `@label`. */
    text: string;
    /** Structured source sessions in appearance order (empty when none). */
    references: SessionReferenceInput[];
    /** Aggregated snapshot for `agent.inject()`, undefined without references. */
    additionalContext?: UserMessage;
}
/** Whether a mention token is already navigating a filesystem path. */
export declare function isPathLikeMentionQuery(query: string): boolean;
/** The mention API the input editor and the runner share. */
export interface MentionsApi {
    /** Ranked menu candidates for the typed `@` query. */
    candidates: (query: string, signal?: AbortSignal) => Promise<readonly MentionCandidate[]>;
    /** Parse submission text into readable text plus structured references. */
    parse(text: string): ParsedSessionReferenceText;
    /**
     * Snapshot references and build the injected context. Throws the service's
     * typed error on failure — the caller restores the draft and notifies.
     */
    prepare(parsed: ParsedSessionReferenceText, signal?: AbortSignal): Promise<PreparedMention>;
    /** Canonical mention token for a picked session candidate. */
    sessionMention(candidate: SessionReferenceCandidate): string;
}
/**
 * Create the mention API for one agent's workspace. A missing
 * `fileReferences` service (with an agent present) or `sessionReferenceResolver`
 * degrades that half to empty rows; `prepare` passes text through untouched
 * without references. An undefined agent (a bare launch before any session
 * exists) runs the official WorkspaceFileSearch over the launch cwd — the
 * same class the mounted service uses per agent — so `@` file completion
 * works from the first keystroke; session references wait for the session.
 *
 * `candidates` never reaches for `this` — the runner hands it to the input
 * editor as a detached callback, and a `this`-bound method would throw on
 * every `@` key.
 * @param ctx - context carrying the optional `fileReferences` and
 * `sessionReferenceResolver` services.
 * @param agent - the session owner; excluded from its own session candidates.
 * @param cwd - launch working directory; bounds the pre-session search.
 */
export declare function createMentions(ctx: Context, agent: Agent | undefined, cwd: string): MentionsApi;
export {};