/**
 * Messaging layer — Protocol v2's named grouping of conversational metadata
 * fields that ride on the {@link MessageV2} envelope.
 *
 * The `Message` back-compat alias (defined in `index.ts`) keeps top-level
 * `senderId`, `mentions`, and `reactions` fields for backward compatibility.
 * The v2 envelope ({@link MessageV2}) carries those plus `recipientIds` and
 * `reply` under a single `meta` field typed as {@link MessageMeta}.
 *
 * `MessageMeta` is generic over an extensions type parameter so host platforms
 * can add typed metadata fields (e.g. `priority`, `archived`) without forking
 * the framework. Framework-side code uses the default form
 * (`MessageMeta<Record<string, never>>`); platforms declare their own
 * extension type and use the typed alias at their boundaries.
 *
 * @see {@link MessageV2} envelope
 * @see {@link ProtocolVersion}
 *
 * @category Messaging
 * @since 2.0.0
 */
import type { Mention } from "./mentions.js";
import type { Reaction } from "./reactions.js";
/**
 * Optional reply context attached to a message. The runner / platform
 * formats this as a quoted preamble in the prompt sent to the agent — the
 * agent SDK never sees this object directly.
 *
 * In v1 this was {@link PromptReplyTo} on `protocol.ts`; v2 renames it
 * to `ReplyRef` and moves it to the messaging layer.
 *
 * @category Messaging
 * @since 2.0.0
 * @docLink packages/types/messages#reply-ref
 */
export type ReplyRef = {
    /** Database id of the message being replied to. */
    messageId: string;
    /** Display name of the parent message's sender (incl. `"Assistant"` for agent). */
    senderName: string;
    /** First ~120 chars of the parent payload text. */
    snippet: string;
    /** Monotonic seq of the parent message in the same session. */
    seq: number;
};
/**
 * Conversational metadata for the v2 {@link MessageV2} envelope. All fields
 * are optional; minimal clients can omit `meta` entirely.
 *
 * `MessageMeta` is **generic over an extensions type parameter** so host
 * platforms can add typed fields without forking the framework. The default
 * form (no type argument) is the framework-standard shape.
 *
 * @example Platform-side aliasing for typed extensions:
 * ```ts
 * type PlatformMetaExtensions = {
 *   priority?: 'low' | 'normal' | 'high'
 *   archived?: boolean
 * };
 * export type PlatformMessageMeta = MessageMeta<PlatformMetaExtensions>;
 * ```
 *
 * # Round-trip preservation contract
 *
 * Implementations that store and replay `MessageMeta` MUST preserve unknown
 * fields on round-trip. A v1-aware client reading a v2-emitted message must
 * still emit the v2 extension fields back to other consumers when it
 * forwards the message — even though it cannot interpret them.
 *
 * In practice, this is a one-line spread in any persistence layer
 * (`{ ...row.meta, priority: 'high' }`); it does not need a framework-provided
 * codec. Each platform implements its own meta-to-storage mapping according to
 * its DB schema (separate JSONB column, per-field columns, merged into payload,
 * etc.). The framework's responsibility ends at the type definitions and the
 * contract.
 *
 * @typeParam TExtensions - platform-specific extension fields, defaults to no extensions.
 *
 * @category Messaging
 * @since 2.0.0
 * @docLink packages/types/messages#message-meta
 */
export type MessageMeta<TExtensions extends object = Record<string, never>> = TExtensions & {
    /** User attribution for user-originated payloads; `undefined` denotes the agent. */
    senderId?: string;
    /**
     * Recipients of the message:
     * - missing or `[]` — broadcast to all session members (current behavior)
     * - `[userId]` — private message to one recipient
     * - `[userId, userId, ...]` — group message to a subset
     * - `["agent"]` — agent-to-agent direct (whisper); not displayed to humans
     *
     * Enforcement (filtering, persistence) is up to the host platform.
     */
    recipientIds?: string[];
    /** Optional reply-context for threading. */
    reply?: ReplyRef;
    /** `@`-mentions parsed from the message text, if any. */
    mentions?: Mention[];
    /** Emoji reactions on this message, if any. */
    reactions?: Reaction[];
};
export type { Mention, MentionGroup } from "./mentions.js";
export type { Reaction } from "./reactions.js";
//# sourceMappingURL=messaging.d.ts.map