/**
 * @license
 * Copyright 2026 Qwen Team
 * SPDX-License-Identifier: Apache-2.0
 */
/** Bumped only when the shape of an existing field changes. */
export declare const PEER_FRAME_VERSION = 1;
/**
 * Longest line either side accepts, in UTF-16 code units.
 *
 * Counted on the decoded string rather than in bytes: both ends compare it
 * against a JS string, and re-encoding every line just to count bytes would
 * cost more than the precision is worth. A receiver drops the connection on
 * a longer line, so a sender measures first and fails with a reason instead
 * of a bare reset.
 */
export declare const MAX_FRAME_CHARS: number;
/**
 * Most ids one `dropped` receipt settles beyond the one it is addressed for.
 * The list is drawn from ids senders chose, so it is bounded like every
 * other array that crosses a process boundary.
 */
export declare const MAX_DROPPED_MSG_IDS = 256;
/** How a delivered message competes with whatever the recipient is doing. */
export type PeerMessagePriority = 'now' | 'next';
/**
 * The review class a sender asserts: `prompting` when a person reviews each
 * action, `bypass` when some apply without review. A claim, not a
 * credential; a program that is not a coding session has no honest value to
 * give and should leave it out.
 */
export type PeerModeClass = 'bypass' | 'prompting';
/** Which wall a `dropped` message met. */
export type PeerDropReason = 'rate-limited' | 'duplicate' | 'queue-full';
/**
 * What became of a message on the receiving side.
 *
 * The one list of them: the type is derived from it, so the set the parser
 * accepts cannot drift from the set the type names.
 */
export declare const PEER_DELIVERY_STATUSES: readonly ["held", "denied", "refused", "expired", "delivered", "misaddressed", "dropped"];
export type PeerDeliveryStatus = (typeof PEER_DELIVERY_STATUSES)[number];
export interface PeerUserFrame {
    msgV: number;
    msgId: string;
    type: 'user';
    /** The sender's own inbox path, where receipts go. */
    from?: string;
    /** The token the sender's inbox requires, so receipts authenticate. */
    replyToken?: string;
    fromName?: string;
    fromMode?: PeerModeClass;
    /** The session id the sender read from the recipient's record. */
    toSessionId?: string;
    priority: PeerMessagePriority;
    message: {
        role: 'user';
        content: string;
    };
}
export interface PeerControlFrame {
    msgV: number;
    msgId: string;
    type: 'control';
    action: 'delivery_status';
    status: PeerDeliveryStatus;
    /** The `msgId` this receipt reports on. */
    origMsgId: string;
    from?: string;
    /** Free text for a person. Never parse it. */
    reason?: string;
    /** Only meaningful with `status: 'dropped'`. */
    dropReason?: PeerDropReason;
    /** Further ids this receipt settles. Only with `status: 'dropped'`. */
    droppedMsgIds?: string[];
}
export type PeerFrame = PeerUserFrame | PeerControlFrame;
/** Dashes stripped, case folded: the form every id comparison uses. */
export declare function canonicalizeMsgId(msgId: string): string;
export declare function isPeerMsgId(value: unknown): value is string;
/**
 * Parse one line into a frame, or return null.
 *
 * A higher `msgV`, an unknown `type` and a malformed field all come back as
 * null rather than an error: nothing about an unintelligible line is worth
 * interrupting anyone for.
 */
export declare function parsePeerFrame(line: string): PeerFrame | null;
/** One frame as one line, terminator included. */
export declare function encodePeerFrame(frame: PeerFrame): string;
/**
 * The first line of a connection to an inbox that requires a token.
 *
 * Shaped like a frame, so an inbox that requires no token reads it as an
 * unknown type and skips it: leading with it is always safe.
 */
export declare function buildAuthLine(token: string): string;
/** The token an auth line presents, or null when the line is not one. */
export declare function parsePeerAuthLine(line: string): string | null;
export interface BuildUserFrameFields {
    content: string;
    from?: string;
    replyToken?: string;
    fromName?: string;
    fromMode?: PeerModeClass;
    toSessionId?: string;
    priority?: PeerMessagePriority;
}
export declare function buildUserFrame(fields: BuildUserFrameFields): PeerUserFrame;
export interface BuildDeliveryStatusFields {
    status: PeerDeliveryStatus;
    origMsgId: string;
    from?: string;
    reason?: string;
    dropReason?: PeerDropReason;
    droppedMsgIds?: readonly string[];
}
export declare function buildDeliveryStatusFrame(fields: BuildDeliveryStatusFields): PeerControlFrame;
/** A sentence for a person about what a status means for the sender. */
export declare function describeDeliveryStatus(status: PeerDeliveryStatus): string;