/**
 * Server-side agent presence lifecycle for collaborative editing.
 *
 * Provides enter/leave semantics so the agent behaves like a real
 * collaborator — it "enters" a document, its edits are visible with
 * durable presence, and it "leaves" when done. Actions call these
 * instead of hand-rolling HTTP awareness calls.
 *
 * Presence lingers after the agent finishes editing (default 6s) so viewers
 * get a moment to see who just changed what — the same way a human
 * collaborator's cursor doesn't vanish the instant they stop typing. Recent
 * edits are attributed in the awareness state (`recentEdits`, `lastEditAt`)
 * so clients can render fading highlights over the edited regions.
 *
 * On serverless hosts the linger timer may never fire after the response is
 * sent; the 30s awareness expiry then removes the entry, so presence degrades
 * to "up to 30s" instead of leaking.
 */
import { type RecentEdit } from "./recent-edits.js";
/** How long agent presence lingers after leave/last edit before clearing. */
export declare const AGENT_PRESENCE_LINGER_MS = 6000;
/**
 * Mark the agent as present on a document.
 *
 * Sets an awareness entry for the agent and starts a heartbeat that
 * keeps it alive. If the agent is already present on this doc (including
 * lingering after a previous edit), refreshes state without creating a
 * second interval.
 */
export declare function agentEnterDocument(docId: string, metadata?: Record<string, unknown>): void;
export interface AgentLeaveOptions {
    /**
     * How long presence lingers before the awareness entry clears.
     * Defaults to {@link AGENT_PRESENCE_LINGER_MS}. Pass 0 to clear
     * immediately (e.g. when an operation failed before editing anything).
     */
    lingerMs?: number;
}
/**
 * Release the agent's presence on a document.
 *
 * Decrements the reference count; when it reaches zero the awareness entry
 * lingers for `lingerMs` (default 6s) and is then removed. Viewers see the
 * agent avatar/highlights for a beat after the edit completes instead of an
 * instant disappearance.
 */
export declare function agentLeaveDocument(docId: string, options?: AgentLeaveOptions): void;
/**
 * Update the agent's awareness state to include selection info
 * (e.g., which track, panel, or element the agent is working on).
 */
export declare function agentUpdateSelection(docId: string, selection: Record<string, unknown>): void;
export interface AgentTouchOptions {
    /** Region descriptor + label recorded in the agent's recentEdits ring. */
    edit?: Omit<RecentEdit, "at"> & {
        at?: number;
    };
    /** Extra awareness fields to merge (e.g. `selection`). */
    metadata?: Record<string, unknown>;
    /** Linger before auto-clearing when no enter/leave pair is active. */
    lingerMs?: number;
}
/**
 * Record an agent edit on a document without requiring an explicit
 * enter/leave pair. Used by the collab write paths so ANY agent edit
 * produces visible presence + lingering attribution automatically.
 *
 * - Upserts the agent awareness entry (identity preserved/merged).
 * - Appends to the `recentEdits` ring and bumps `lastEditAt`.
 * - When no explicit operation is in flight (refcount 0), (re)schedules a
 *   linger removal so presence fades out on its own.
 */
export declare function agentTouchDocument(docId: string, options?: AgentTouchOptions): void;
/**
 * Apply search-and-replace edits incrementally so each one appears
 * as a separate poll event to connected clients.
 *
 * Enters the document before editing and leaves in a finally block.
 */
export declare function agentApplyEditsIncrementally(docId: string, edits: Array<{
    find: string;
    replace: string;
}>, options?: {
    delayMs?: number;
}): Promise<void>;
/**
 * Apply structured data patches incrementally so each one appears
 * as a separate poll event to connected clients.
 *
 * Enters the document before patching and leaves in a finally block.
 */
export declare function agentApplyPatchesIncrementally(docId: string, fieldName: string, patches: Array<{
    op: string;
    path: string;
    value?: unknown;
    index?: number;
    from?: number;
    to?: number;
}>, options?: {
    delayMs?: number;
}): Promise<void>;
//# sourceMappingURL=agent-presence.d.ts.map