/**
 * Running one host command against a conversation, from the agent's own idle
 * phase, one at a time.
 *
 * Every command APPENDS to the session log, and the log takes one writer. This
 * channel learned that twice — once as a torn record that cost a whole session,
 * once as `session append cannot reenter while another append is being
 * published` — and both times the answer looked like timing: watch `turn/end`,
 * step out of the dispatch, retry on a message the host happened to print.
 * That was guesswork about someone else's schedule.
 *
 * The host publishes the real thing. `runMaintenance` claims the true idle
 * phase synchronously, holds later waking input in the inbox until the task
 * settles, and refuses when a turn or another maintenance task already owns the
 * agent; `whenIdle` resolves when the agent has nothing running. So the rule
 * here is: ask the agent for the phase, and let it say when. What this module
 * adds is one queue per conversation, so two clicks are two turns of the queue
 * rather than two writers.
 * @module dsh-lark-channel/maintenance
 */
import type { HostAgent } from './host.ts';
/** Why a host cannot run maintenance at all, said the way a chat can read it. */
export declare const NO_IDLE_PHASE = "this host does not offer an idle phase to run commands from";
/**
 * Whether one agent can lend its idle phase. Structural rather than versioned:
 * the host contract reaches this plugin as an object, not as a dependency
 * range, so the capability is asked of the object.
 * @param agent - the agent to test.
 * @returns true when both halves of the contract are present.
 */
export declare function lendsIdlePhase(agent: HostAgent): boolean;
/** One conversation's serialized maintenance work. */
export interface MaintenanceQueue {
    /**
     * Run one task from the conversation's idle phase, after everything already
     * queued for it.
     * @param sessionId - the conversation's session, which is the queue's key.
     * @param agent - the agent whose phase is claimed.
     * @param task - the work; its signal aborts on cancellation and disposal.
     * @returns the task's own result.
     * @throws when the queue is closed, the work is cancelled, the host lends no
     * idle phase, or the task itself fails.
     */
    run<T>(sessionId: string, agent: HostAgent, task: (signal: AbortSignal) => Promise<T>): Promise<T>;
    /**
     * Abort what one conversation has queued.
     * @param sessionId - the conversation to stop.
     * @returns when its work has unwound, so a caller may release the agent
     * knowing nothing is about to write to it.
     */
    cancel(sessionId: string): Promise<void>;
    /** Abort everything and wait for it to unwind. Idempotent. */
    close(): Promise<void>;
}
/** Cancellation, as its own type so a caller can tell it from a real failure. */
export declare class MaintenanceCancelled extends Error {
    constructor(sessionId: string);
}
/**
 * Build a queue. One per bridge: its keys are session ids, which are unique
 * across conversations by construction.
 * @returns the queue.
 */
export declare function createMaintenanceQueue(): MaintenanceQueue;
//# sourceMappingURL=maintenance.d.ts.map