/** Default delivery TTL for messages enqueued without an explicit one (24 hours). */
export declare const DEFAULT_TTL_SECONDS: number;
/** Env var that overrides {@link DEFAULT_TTL_SECONDS} with a duration like "24h" or "3600". */
export declare const MAILBOX_TTL_ENV = "AGENTS_MAILBOX_TTL";
/**
 * Resolve the default mailbox TTL in seconds. Honors `AGENTS_MAILBOX_TTL`
 * (parsed by {@link parseDuration}); falls back to 24h. A malformed env value
 * fails loud instead of silently disabling expiry.
 */
export declare function resolveDefaultTtlSeconds(): number;
/** A single mailbox message. `text` may embed `host:/path` clip tokens. */
export interface MailboxMessage {
    /** Unique, time-sortable id. Also the on-disk filename stem. */
    msgId: string;
    /** The mailboxId this message is addressed to (anti-misroute stamp). */
    to: string;
    /** Who sent it (operator label / agent id / host). Optional. */
    from?: string;
    /** ISO-8601 creation time. */
    ts: string;
    /** Optional ISO-8601 expiry time. Expired messages are dropped, not delivered. */
    expiresAt?: string;
    /** The message body. */
    text: string;
    /**
     * The feed block this message answers. Set by `agents message` when the
     * target has an open block, so the drain can surface consumed/continued
     * receipts back to the feed store.
     */
    blockId?: string;
    /**
     * Drop reason when a message is archived without delivery (expired, dead box, etc.).
     * Set by the TTL/liveness layer, not by writers.
     */
    dropped?: string;
}
/**
 * A mailboxId must be a single, separator-free path segment. Real ids (session
 * UUID / teams agentId / loop runId) already satisfy this; rejecting anything
 * else fails loud instead of silently misrouting — a message whose id contained
 * a `/` would nest under a different dir than the `to` stamp it is matched
 * against, and would be dropped with no error. Also blocks `.`/`..` traversal
 * once `agents message` starts accepting external target ids.
 */
export declare function isValidMailboxId(mailboxId: string): boolean;
export declare function assertValidMailboxId(mailboxId: string): void;
/** Absolute path to a box. `root` override is for tests. */
export declare function mailboxDir(mailboxId: string, root?: string): string;
/**
 * Enqueue a message into `boxDir` atomically. Returns the msgId. The `to` field
 * is stamped so a drain can refuse a message that lands in the wrong box.
 */
export declare function enqueue(boxDir: string, msg: {
    to: string;
    text: string;
    from?: string;
    blockId?: string;
    ttlSeconds?: number;
}): string;
/** Parse a message file. Returns null on missing/corrupt/invalid-shape. */
export declare function readMessage(file: string): MailboxMessage | null;
/** True when a message has a parsed expiry in the past. */
export declare function isExpired(msg: MailboxMessage, now?: Date): boolean;
/**
 * Move expired messages from inbox/ and processing/ into consumed/ with a
 * `dropped: expired` marker. Called by drain/peek before returning messages.
 *
 * When a dropped message carries a `blockId`, a failure receipt is surfaced
 * back to the feed store so the sender sees the bounce.
 */
export declare function sweepExpired(boxDir: string, boxId?: string, now?: Date, feedRoot?: string): number;
/**
 * Drain the box: return every pending message addressed to it, in FIFO order,
 * removing them from the queue. Claim-first (inbox → processing → consumed) so
 * an interrupted drain is recovered on the next call (at-least-once). Corrupt
 * files and messages addressed to a different box are dropped, not returned.
 *
 * `boxId` defaults to the box's directory name — the id it was created under.
 */
export declare function drain(boxDir: string, boxId?: string, now?: Date): MailboxMessage[];
/** Read pending messages (inbox + in-flight) without consuming them. FIFO. */
export declare function peek(boxDir: string, boxId?: string, now?: Date): MailboxMessage[];
/** Delete pending (not-yet-claimed) inbox messages. Returns the count removed. */
export declare function clear(boxDir: string): number;
/** Which bucket a stored message currently sits in. */
export type MailboxState = 'inbox' | 'processing' | 'consumed';
/** A message read back from a box, tagged with the bucket it was found in. */
export interface StoredMessage extends MailboxMessage {
    state: MailboxState;
}
/** A stored message enriched with the mailbox identity used by comms renderers. */
export interface CommsMsg {
    from: string;
    to: string;
    toLabel: string;
    ts: string;
    text: string;
    state: MailboxState;
    box: string;
}
/**
 * Enumerate the box ids under `root` (directory names that are valid mailbox
 * ids). Read-only; does not create the root. Sorted for stable output.
 */
export declare function listBoxes(root?: string): string[];
/**
 * Read every message in a box across all three buckets (inbox, processing,
 * consumed) WITHOUT consuming, sweeping, or archiving anything. Unlike `peek`,
 * this includes `consumed/` — the delivered history — so callers can surface a
 * communication log. Each row is tagged with its bucket. Sorted FIFO by msgId
 * (which is time-sortable), oldest first.
 */
export declare function readBox(boxDir: string): StoredMessage[];
/**
 * Poll the complete spool and yield each message once when its box/msgId pair
 * first appears. Existing messages establish the initial baseline unless
 * `backfill` is requested; moving a message between buckets does not re-emit it.
 */
export declare function watchMessages(root: string, opts: {
    signal?: AbortSignal;
    intervalMs?: number;
    backfill?: boolean;
}): AsyncGenerator<CommsMsg>;
