@gorlitzer-labs/apiary 1.13.3

package/dist/index-Dp3QSGog.d.ts

@@ -0,0 +1,837 @@
+import { z } from 'zod';
+
+/** Core types for apiary — messages, participants, pagination. */
+
+/**
+ * The four top-level categories events are grouped under.
+ *
+ * Channels subscribe to one or more categories — they only receive events in
+ * their subscription set. Use this to filter what an agent or observer sees:
+ *
+ * - MESSAGE  — chat messages and reactions (sent, edited, deleted, reacted)
+ * - PRESENCE — participants joining and leaving
+ * - ACTIVITY — agent activity (thinking, tool use, mode changes, compaction)
+ * - MENTION  — direct @mentions delivered only to the mentioned participant
+ */
+declare const EventCategory: {
+    readonly MESSAGE: "MESSAGE";
+    readonly PRESENCE: "PRESENCE";
+    readonly ACTIVITY: "ACTIVITY";
+    readonly MENTION: "MENTION";
+};
+type EventCategory = (typeof EventCategory)[keyof typeof EventCategory];
+/**
+ * A file or image attached to a message. Discriminated union on `type`.
+ *
+ * - `type: "path"` — local filesystem reference, intended for same-machine rooms.
+ *   Receivers should gracefully handle the case where the path is not accessible
+ *   on their machine (e.g. multi-machine rooms with a tunnel).
+ *
+ * - `type: "upload"` — server-hosted bytes, fetched via `GET /attachment/:id`
+ *   with a valid session token. URL uses the server's `publicUrl` (tunnel URL
+ *   when active, otherwise localhost).
+ */
+declare const AttachmentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"path">;
+    id: z.ZodString;
+    name: z.ZodString;
+    mime_type: z.ZodString;
+    size: z.ZodOptional<z.ZodNumber>;
+    path: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"upload">;
+    id: z.ZodString;
+    name: z.ZodString;
+    mime_type: z.ZodString;
+    size: z.ZodNumber;
+    url: z.ZodString;
+}, z.core.$strip>], "type">;
+type Attachment = z.infer<typeof AttachmentSchema>;
+/**
+ * A chat message. Immutable once stored — edits and deletes are separate events.
+ *
+ * - `id`                — UUID, assigned by the room on creation
+ * - `room_id`           — the room this message belongs to
+ * - `sender_id`         — participant ID of the author
+ * - `sender_name`       — display name at the time of sending (denormalized)
+ * - `content`           — text body (may be empty if the message is image-only)
+ * - `reply_to_id`       — if set, this message is a reply to that message ID
+ * - `recipients`        — if non-empty, this is a whisper: only these participant IDs (plus the sender) can read it
+ * - `attachments`       — zero or more file/image attachments
+ * - `image_url`         — legacy single-image URL (kept for backward compat)
+ * - `image_mime_type`   — MIME type of the legacy image
+ * - `image_size_bytes`  — size of the legacy image in bytes
+ * - `timestamp`         — creation time (UTC)
+ */
+declare const MessageSchema: z.ZodObject<{
+    id: z.ZodDefault<z.ZodString>;
+    room_id: z.ZodString;
+    sender_id: z.ZodString;
+    sender_name: z.ZodString;
+    content: z.ZodString;
+    reply_to_id: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    recipients: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    attachments: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"path">;
+        id: z.ZodString;
+        name: z.ZodString;
+        mime_type: z.ZodString;
+        size: z.ZodOptional<z.ZodNumber>;
+        path: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"upload">;
+        id: z.ZodString;
+        name: z.ZodString;
+        mime_type: z.ZodString;
+        size: z.ZodNumber;
+        url: z.ZodString;
+    }, z.core.$strip>], "type">>>;
+    image_url: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    image_mime_type: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    image_size_bytes: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
+    timestamp: z.ZodDefault<z.ZodDate>;
+}, z.core.$strip>;
+type Message = z.infer<typeof MessageSchema>;
+/**
+ * Authority level — what a participant is allowed to do.
+ *
+ * - `admin`         — full control: kick, promote, clear, tunnel, generate all links
+ * - `product_owner` — can mute/unmute members, set engagement modes, generate member/guest links
+ * - `member`        — can send messages, set own mode, generate member/guest links
+ * - `guest`         — read-only: can catch up and search, but can't send or act
+ *
+ * Set on join via share token. Admins can change authority mid-session via /promote, /demote, /mute, /unmute.
+ */
+type AuthorityLevel = "admin" | "product_owner" | "member" | "guest";
+/** Whether a participant is a human or an agent. */
+type ParticipantType = "human" | "agent";
+/**
+ * A participant in a room.
+ *
+ * - `id`         — stable unique ID across all rooms and sessions
+ * - `name`       — display name (mutable — participants can rename)
+ * - `status`     — current presence status ("online", "offline", etc.)
+ * - `type`       — "human" or "agent"
+ * - `identifier` — optional stable @-mention slug, e.g. "my-agent".
+ *                  Unlike `name`, this never changes on rename.
+ *                  Used for @-mention matching in addition to the display name.
+ *                  Not all participants have one — guests and anonymous users
+ *                  typically don't.
+ * - `authority`  — optional authority level. Defaults to "member" if unset.
+ */
+interface Participant {
+    id: string;
+    name: string;
+    status: string;
+    type: ParticipantType;
+    identifier?: string;
+    authority?: AuthorityLevel;
+}
+/**
+ * A page of results with a cursor for fetching the previous page.
+ *
+ * All paginated queries return results newest-first. Pass `next_cursor` back
+ * to the same query to continue paginating backwards through history.
+ *
+ * - `items`       — results for this page (newest-first)
+ * - `next_cursor` — pass this to get the next (older) page; null when exhausted
+ * - `has_more`    — true if there are older items beyond this page
+ */
+interface PaginatedResult<T> {
+    items: T[];
+    next_cursor: string | null;
+    has_more: boolean;
+}
+
+/**
+ * Typed events for rooms — a discriminated union on the `type` field.
+ *
+ * Every event has:
+ *   id           — UUID assigned at creation
+ *   type         — the discriminant (e.g. "MessageSent", "ParticipantJoined")
+ *   category     — the EventCategory for subscription filtering
+ *   room_id      — the room this event belongs to
+ *   participant_id — the participant who caused the event
+ *   timestamp    — UTC creation time
+ *
+ * Use `createEvent()` to build events — it fills in `id` and `timestamp`.
+ * Use `EVENT_ROLE` to classify events by their semantic role.
+ */
+
+interface BaseRoomEvent {
+    /** UUID assigned at creation. */
+    id: string;
+}
+/** Someone sent a message. `message` contains the full content including any image. */
+interface MessageSentEvent extends BaseRoomEvent {
+    type: "MessageSent";
+    category: "MESSAGE";
+    room_id: string;
+    participant_id: string;
+    timestamp: Date;
+    message: Message;
+}
+/** A message's text content was changed. Does not update image attachments. */
+interface MessageEditedEvent extends BaseRoomEvent {
+    type: "MessageEdited";
+    category: "MESSAGE";
+    room_id: string;
+    participant_id: string;
+    timestamp: Date;
+    message_id: string;
+    new_content: string;
+    old_content: string;
+}
+/** A message was removed. The message ID is preserved for reference but content is gone. */
+interface MessageDeletedEvent extends BaseRoomEvent {
+    type: "MessageDeleted";
+    category: "MESSAGE";
+    room_id: string;
+    participant_id: string;
+    timestamp: Date;
+    message_id: string;
+}
+/** A participant added an emoji reaction to a message. */
+interface ReactionAddedEvent extends BaseRoomEvent {
+    type: "ReactionAdded";
+    category: "MESSAGE";
+    room_id: string;
+    participant_id: string;
+    timestamp: Date;
+    message_id: string;
+    emoji: string;
+}
+/** A participant removed their emoji reaction from a message. */
+interface ReactionRemovedEvent extends BaseRoomEvent {
+    type: "ReactionRemoved";
+    category: "MESSAGE";
+    room_id: string;
+    participant_id: string;
+    timestamp: Date;
+    message_id: string;
+    emoji: string;
+}
+/**
+ * A participant connected to the room.
+ *
+ * Not emitted for silent connects (`Room.connect(..., silent: true)`).
+ * Agents connect silently to avoid polluting the chat with join noise.
+ */
+interface ParticipantJoinedEvent extends BaseRoomEvent {
+    type: "ParticipantJoined";
+    category: "PRESENCE";
+    room_id: string;
+    participant_id: string;
+    timestamp: Date;
+    /** Full participant snapshot at join time. */
+    participant: Participant;
+}
+/**
+ * A participant disconnected from the room.
+ *
+ * Not emitted for silent disconnects (`channel.disconnect(true)`).
+ */
+interface ParticipantLeftEvent extends BaseRoomEvent {
+    type: "ParticipantLeft";
+    category: "PRESENCE";
+    room_id: string;
+    participant_id: string;
+    timestamp: Date;
+    /** Full participant snapshot at leave time. */
+    participant: Participant;
+}
+/**
+ * A participant's presence status changed.
+ *
+ * Emitted by the server for all presence transitions:
+ * - `online → unresponsive`  — first ping timeout threshold missed (reason: "ping_timeout")
+ * - `unresponsive → online`  — SSE reconnect recovery (reason: "recovered")
+ * - `unresponsive → offline` — sustained timeout, second threshold missed (reason: "ping_timeout")
+ * - `online → offline`       — clean disconnect (reason: "left") or admin kick (reason: "kicked")
+ *
+ * The `"left"` and `"kicked"` variants are companion events emitted alongside
+ * `ParticipantLeftEvent` / `ParticipantKickedEvent` for state-machine consumers
+ * that only want a single event type for presence tracking.
+ *
+ * `previous_status: "offline"` never appears — re-entry is `ParticipantJoinedEvent`.
+ */
+interface StatusChangedEvent extends BaseRoomEvent {
+    type: "StatusChanged";
+    category: "PRESENCE";
+    room_id: string;
+    participant_id: string;
+    timestamp: Date;
+    /** Display name of the affected participant. */
+    name: string;
+    status: "online" | "unresponsive" | "offline";
+    previous_status: "online" | "unresponsive" | "offline";
+    reason: "ping_timeout" | "recovered" | "left" | "kicked";
+}
+/**
+ * A participant was kicked from the room by an admin.
+ *
+ * Emitted before the channel disconnect so all participants see it.
+ * The subsequent `ParticipantLeft` event is suppressed (silent disconnect).
+ */
+interface ParticipantKickedEvent extends BaseRoomEvent {
+    type: "ParticipantKicked";
+    category: "PRESENCE";
+    room_id: string;
+    /** The kicked participant. */
+    participant_id: string;
+    timestamp: Date;
+    /** Full participant snapshot at kick time. */
+    participant: Participant;
+    /** Display name of the admin who kicked them. */
+    kicked_by: string;
+}
+/**
+ * A participant's authority level was changed by an admin.
+ *
+ * Covers mute (→ guest), unmute (→ member), and promotion (→ admin).
+ */
+interface AuthorityChangedEvent extends BaseRoomEvent {
+    type: "AuthorityChanged";
+    category: "PRESENCE";
+    room_id: string;
+    /** The affected participant. */
+    participant_id: string;
+    timestamp: Date;
+    /** Full participant snapshot (with updated authority). */
+    participant: Participant;
+    /** The new authority level. */
+    new_authority: AuthorityLevel;
+    /** Display name of the admin who made the change. */
+    changed_by: string;
+}
+/**
+ * An agent made an MCP tool call.
+ *
+ * Emitted twice per tool call: once with `status: "started"` (before the call)
+ * and once with `status: "completed"` (after). Useful for showing live tool
+ * progress in a UI.
+ */
+interface ToolUseEvent extends BaseRoomEvent {
+    type: "ToolUse";
+    category: "ACTIVITY";
+    room_id: string;
+    participant_id: string;
+    timestamp: Date;
+    tool_name: string;
+    /** "started" before the call, "completed" after. */
+    status: "started" | "completed";
+}
+/**
+ * A generic activity event for platform-specific actions.
+ *
+ * Used when no specific event type fits. The `action` field identifies the
+ * action (e.g. `"mode_changed"`), and `detail` carries structured metadata.
+ *
+ * Current usages:
+ *   - action: "mode_changed", detail: { mode: EngagementMode }
+ *     Emitted when an agent's engagement mode changes for a room.
+ */
+interface ActivityEvent extends BaseRoomEvent {
+    type: "Activity";
+    category: "ACTIVITY";
+    room_id: string;
+    participant_id: string;
+    timestamp: Date;
+    action: string;
+    detail: Record<string, unknown> | null;
+}
+/**
+ * An agent's context window was compacted.
+ *
+ * Fired when the LLM backend summarizes and compresses the conversation history
+ * to free up context space. After compaction, the agent re-reads all rooms via
+ * `catch_up` to rebuild its working context.
+ */
+interface ContextCompactedEvent extends BaseRoomEvent {
+    type: "ContextCompacted";
+    category: "ACTIVITY";
+    room_id: string;
+    participant_id: string;
+    timestamp: Date;
+    /** Full participant snapshot (for display name). */
+    participant: Participant;
+}
+/**
+ * An admin cleared the room history.
+ *
+ * All clients should discard their local event/message state and start fresh.
+ * The event itself is broadcast but NOT persisted (storage is already wiped).
+ */
+interface RoomClearedEvent extends BaseRoomEvent {
+    type: "RoomCleared";
+    category: "ACTIVITY";
+    room_id: string;
+    participant_id: string;
+    timestamp: Date;
+    /** Display name of the admin who cleared the room. */
+    cleared_by: string;
+}
+/**
+ * Room rules were created or updated.
+ *
+ * Emitted when the rules file changes — either via `PUT /rules` (admin) or
+ * when the underlying `~/.apiary/rooms/<name>.rules.md` file is hand-edited
+ * (mtime watch). Surfaced by `apiary__catch_up` so long-running agents
+ * re-discover the current ruleset after compaction or mid-session edits.
+ */
+interface RulesChangedEvent extends BaseRoomEvent {
+    type: "RulesChanged";
+    category: "ACTIVITY";
+    room_id: string;
+    participant_id: string;
+    timestamp: Date;
+    /** The full ruleset in effect after this change. */
+    rules: string[];
+    /** Display name of the actor who updated the rules; "[system]" if hand-edit. */
+    updated_by: string;
+}
+/**
+ * A participant was @mentioned in a message.
+ *
+ * Delivered only to the mentioned participant's channel — not broadcast to the
+ * room. The `participant_id` is the **recipient** (the person mentioned), not
+ * the sender. The sender is in `message.sender_id`.
+ *
+ * @mention detection is case-insensitive and matches on both `identifier`
+ * (e.g. `@my-agent`) and display `name` (e.g. `@Alice`).
+ *
+ * Agents in standby modes wake up on this event type only.
+ */
+interface MentionedEvent extends BaseRoomEvent {
+    type: "Mentioned";
+    category: "MENTION";
+    room_id: string;
+    /** The mentioned participant (the recipient of the @mention). */
+    participant_id: string;
+    timestamp: Date;
+    /** The full message that contained the @mention. */
+    message: Message;
+}
+/**
+ * A participant was pinged for a status check.
+ *
+ * Delivered to the pinged participant's channel and all observers.
+ * Unlike @mentions, pings are non-blocking: active agents see them as
+ * buffered context ("content"), not triggers. Standby agents wake on ping.
+ */
+interface PingedEvent extends BaseRoomEvent {
+    type: "Pinged";
+    category: "MENTION";
+    room_id: string;
+    /** The pinged participant (the recipient). */
+    participant_id: string;
+    timestamp: Date;
+    /** Participant ID of the person who sent the ping. */
+    pinger_id: string;
+    /** Display name of the person who sent the ping. */
+    pinger_name: string;
+}
+/**
+ * A whisper was sent to specific participants.
+ *
+ * Broadcast to all participants NOT in the whisper, so they know a private
+ * conversation is happening without seeing the content. Sender and recipients
+ * receive the full `MessageSentEvent` instead. Not persisted to storage.
+ */
+interface WhisperNotifiedEvent extends BaseRoomEvent {
+    type: "WhisperNotified";
+    category: "ACTIVITY";
+    room_id: string;
+    /** The sender's participant ID (follows the common event convention). */
+    participant_id: string;
+    timestamp: Date;
+    sender_id: string;
+    sender_name: string;
+    recipient_ids: string[];
+    recipient_names: string[];
+}
+type RoomEvent = MessageSentEvent | MessageEditedEvent | MessageDeletedEvent | ReactionAddedEvent | ReactionRemovedEvent | ParticipantJoinedEvent | ParticipantLeftEvent | ParticipantKickedEvent | AuthorityChangedEvent | StatusChangedEvent | ToolUseEvent | ActivityEvent | MentionedEvent | PingedEvent | ContextCompactedEvent | RoomClearedEvent | RulesChangedEvent | WhisperNotifiedEvent;
+/**
+ * Semantic role of an event, used by the engagement system to decide how to
+ * handle it relative to an agent.
+ *
+ * - "message"  — a direct chat message; may trigger LLM evaluation
+ * - "mention"  — an @mention directed at a specific participant
+ * - "ambient"  — background activity (joins, leaves, reactions) — buffered as
+ *                context but doesn't trigger evaluation on its own
+ * - "internal" — platform bookkeeping (edits, deletes, status changes, agent
+ *                activity) — always dropped by the engagement system
+ */
+type EventRole = "message" | "mention" | "ping" | "ambient" | "internal";
+/** Maps each event type to its semantic role for the engagement system. */
+declare const EVENT_ROLE: Record<RoomEvent["type"], EventRole>;
+type EventData<T extends RoomEvent> = Omit<T, "id" | "timestamp"> & {
+    id?: string;
+    timestamp?: Date;
+};
+/**
+ * Create a typed room event, filling in `id` (UUID) and `timestamp` (now).
+ *
+ * @example
+ * const event = createEvent<MessageSentEvent>({
+ *   type: "MessageSent",
+ *   category: "MESSAGE",
+ *   room_id: "room-1",
+ *   participant_id: "user-1",
+ *   message: { ... },
+ * });
+ */
+declare function createEvent<T extends RoomEvent>(data: EventData<T>): T;
+
+declare class Channel {
+    readonly participantId: string;
+    readonly participantName: string;
+    subscriptions: Set<EventCategory>;
+    private _room;
+    private _queue;
+    private _waiters;
+    private _disconnected;
+    constructor(room: Room, participantId: string, participantName: string, subscriptions: Set<EventCategory>);
+    get roomId(): string;
+    /**
+     * Send a chat message from this participant.
+     *
+     * Persists the message to storage, broadcasts a `MessageSentEvent` to all
+     * participants (including the sender), and fires `MentionedEvent` for any
+     * `@name` or `@identifier` patterns found in the content.
+     *
+     * @param content     — message text (may be empty if image is provided)
+     * @param replyToId   — ID of the message being replied to (optional)
+     * @param image       — optional legacy image attachment
+     * @param attachments — optional array of typed attachments
+     * @param recipients  — if non-empty, this is a whisper: only these participant IDs (plus sender) receive it
+     */
+    sendMessage(content: string, replyToId?: string | null, image?: {
+        url: string;
+        mimeType: string;
+        sizeBytes: number;
+    } | null, attachments?: Attachment[], recipients?: string[]): Promise<Message>;
+    /**
+     * Ping another participant for a status check.
+     *
+     * Creates a `PingedEvent` delivered to the target and all observers.
+     * Unlike @mentions, pings are non-blocking for active agents.
+     */
+    ping(targetId: string): Promise<void>;
+    /**
+     * Emit a non-message activity event to the room.
+     *
+     * Use this for platform events: tool use indicators, mode changes, compaction
+     * notices, etc. The event is persisted and broadcast to all subscribed
+     * participants.
+     */
+    emit(event: RoomEvent): Promise<void>;
+    /**
+     * Change which event categories this channel receives.
+     * Takes effect immediately — buffered events from unsubscribed categories
+     * are not retroactively removed.
+     */
+    updateSubscriptions(categories: Set<EventCategory>): void;
+    /**
+     * Leave the room.
+     *
+     * @param silent — if true, suppresses the `ParticipantLeft` broadcast.
+     *                 Agents disconnect silently to avoid chat noise.
+     */
+    disconnect(silent?: boolean): Promise<void>;
+    /** @internal Called by Room to mark this channel as disconnected without removing from room maps. */
+    _markDisconnected(): void;
+    /** @internal Called by Room to deliver an incoming event. Filters by subscription. */
+    _deliver(event: RoomEvent): void;
+    /**
+     * Receive the next event, waiting up to `timeoutMs`.
+     *
+     * Returns null if no event arrives within the timeout. Drains buffered events
+     * before waiting. Used by `EventMultiplexer` to fan-in events from multiple
+     * rooms into a single stream.
+     */
+    receive(timeoutMs: number): Promise<RoomEvent | null>;
+    /**
+     * Async iterator — yields events as they arrive.
+     *
+     * Used by `EventMultiplexer` to fan-in all room channels into a single stream.
+     * The iterator completes when the channel is disconnected.
+     *
+     * @example
+     * for await (const event of channel) {
+     *   console.log(event.type);
+     * }
+     */
+    [Symbol.asyncIterator](): AsyncIterator<RoomEvent>;
+}
+
+/**
+ * Storage protocol and reference implementations for apiary rooms.
+ *
+ * # Implementing StorageProtocol
+ *
+ * Provide your own implementation to persist messages and events to a real
+ * database. Pass it to `new Room(roomId, myStorage)`.
+ *
+ * Pagination contract (applies to all paginated methods):
+ * - Results are returned newest-first.
+ * - `cursor` is the ID of the last item on the previous page (exclusive).
+ *   Pass `null` to start from the most recent.
+ * - `next_cursor` in the result is the cursor to pass for the next (older) page.
+ * - `has_more` is true if there are older items beyond the current page.
+ *
+ * @example
+ * // Minimal Postgres implementation sketch:
+ * class PostgresStorage implements StorageProtocol {
+ *   async addMessage(message) {
+ *     await db.query("INSERT INTO messages ...", [message]);
+ *     return message;
+ *   }
+ *   async getMessage(room_id, message_id) {
+ *     return db.query("SELECT * FROM messages WHERE id = $1", [message_id]);
+ *   }
+ *   async getMessages(room_id, limit = 30, cursor = null) {
+ *     // Fetch `limit` messages before `cursor`, newest-first
+ *     const rows = await db.query("...");
+ *     return { items: rows, next_cursor: ..., has_more: ... };
+ *   }
+ *   async searchMessages(room_id, query, limit = 10, cursor = null) {
+ *     // Full-text search, newest-first
+ *   }
+ *   async addEvent(event) {
+ *     await db.query("INSERT INTO events ...", [event]);
+ *   }
+ *   async getEvents(room_id, category = null, limit = 50, cursor = null) {
+ *     // Optional category filter, newest-first
+ *   }
+ * }
+ */
+
+/**
+ * Persistence interface for a room's messages and events.
+ *
+ * Implement this to back rooms with a real database. The reference
+ * `InMemoryStorage` is suitable for testing and single-process local use.
+ *
+ * All methods operate on a single `room_id` — one storage instance is shared
+ * across all rooms (the `room_id` partitions the data).
+ */
+interface StorageProtocol {
+    /**
+     * Persist a message and return it (with any server-assigned fields set).
+     * Called automatically by `Channel.sendMessage()`.
+     */
+    addMessage(message: Message): Promise<Message>;
+    /**
+     * Look up a single message by ID. Returns null if not found.
+     * Used by agents when resolving reply context and message refs.
+     */
+    getMessage(room_id: string, message_id: string): Promise<Message | null>;
+    /**
+     * Paginate messages for a room, newest-first.
+     *
+     * `cursor` — the `id` of the last message on the previous page (exclusive).
+     *            Pass null to start from the most recent message.
+     */
+    getMessages(room_id: string, limit?: number, cursor?: string | null): Promise<PaginatedResult<Message>>;
+    /**
+     * Full-text search across message content, newest-first.
+     *
+     * `query`  — keyword or phrase to search for (case-insensitive).
+     * `cursor` — pagination cursor (same semantics as `getMessages`).
+     */
+    searchMessages(room_id: string, query: string, limit?: number, cursor?: string | null): Promise<PaginatedResult<Message>>;
+    /**
+     * Persist a room event. Called for every event that passes through the room.
+     * Events are append-only — never updated or deleted.
+     */
+    addEvent(event: RoomEvent): Promise<void>;
+    /**
+     * Paginate events for a room, newest-first.
+     *
+     * `category` — optional filter (e.g. EventCategory.MESSAGE). Pass null for all.
+     * `cursor`   — pagination cursor (index-based for events).
+     */
+    getEvents(room_id: string, category?: EventCategory | null, limit?: number, cursor?: string | null): Promise<PaginatedResult<RoomEvent>>;
+    /**
+     * Delete all messages and events for a room.
+     * Used by the `/clear` command to wipe room history.
+     */
+    clearRoom(room_id: string): Promise<void>;
+}
+/**
+ * Reference in-memory implementation of `StorageProtocol`.
+ *
+ * Suitable for tests, development, and single-process local use. All data is
+ * lost on process restart — not for production.
+ *
+ * One instance can serve multiple rooms (data is partitioned by `room_id`).
+ */
+declare class InMemoryStorage implements StorageProtocol {
+    protected _messages: Map<string, {
+        id: string;
+        room_id: string;
+        sender_id: string;
+        sender_name: string;
+        content: string;
+        reply_to_id: string | null;
+        recipients: string[];
+        attachments: ({
+            type: "path";
+            id: string;
+            name: string;
+            mime_type: string;
+            path: string;
+            size?: number | undefined;
+        } | {
+            type: "upload";
+            id: string;
+            name: string;
+            mime_type: string;
+            size: number;
+            url: string;
+        })[];
+        image_url: string | null;
+        image_mime_type: string | null;
+        image_size_bytes: number | null;
+        timestamp: Date;
+    }[]>;
+    protected _events: Map<string, RoomEvent[]>;
+    addMessage(message: Message): Promise<Message>;
+    getMessage(room_id: string, message_id: string): Promise<Message | null>;
+    getMessages(room_id: string, limit?: number, cursor?: string | null): Promise<PaginatedResult<Message>>;
+    searchMessages(room_id: string, query: string, limit?: number, cursor?: string | null): Promise<PaginatedResult<Message>>;
+    addEvent(event: RoomEvent): Promise<void>;
+    getEvents(room_id: string, category?: EventCategory | null, limit?: number, cursor?: string | null): Promise<PaginatedResult<RoomEvent>>;
+    clearRoom(room_id: string): Promise<void>;
+}
+
+/**
+ * Room — a shared chat space where humans and agents are all just participants.
+ *
+ * Transport-agnostic: no WebSockets, no HTTP. The caller owns the transport
+ * and passes messages/events in via channels. This means the same Room works
+ * identically in a CLI, a web server, or a test.
+ *
+ * # Connecting
+ * Participants connect via `room.connect()`, which returns a `Channel`. The
+ * channel is their bidirectional connection: they send messages and receive
+ * events through it.
+ *
+ * # Observing
+ * Call `room.observe()` to get a read-only-style channel that receives every
+ * event in the room — including targeted @mention events directed at other
+ * participants. Observers are NOT participants: they don't appear in
+ * `listParticipants()` and don't trigger join/leave events.
+ *
+ * # @mention detection
+ * When a message is sent, the Room scans its content for `@token` patterns and
+ * fires a `MentionedEvent` for any participant whose `identifier` or display
+ * `name` matches the token (case-insensitive). The mention event is delivered
+ * to the mentioned participant AND to all observers.
+ *
+ * @example
+ * const storage = new InMemoryStorage();
+ * const room = new Room("room-1", storage);
+ *
+ * const aliceChannel = await room.connect("alice-id", "Alice");
+ * const agentChannel = await room.connect("agent-id", "Agent", "agent", "my-agent");
+ * const observer     = room.observe();
+ *
+ * await aliceChannel.sendMessage("hey @my-agent what do you think?");
+ * // → MessageSentEvent broadcast to all participants + observer
+ * // → MentionedEvent delivered to agentChannel + observer
+ */
+
+declare class Room {
+    readonly roomId: string;
+    /** Direct access to the underlying storage. Useful for bulk reads. */
+    readonly storage: StorageProtocol;
+    private _channels;
+    private _participants;
+    private _observers;
+    private _nextObserverId;
+    /**
+     * @param roomId  — stable identifier for this room (e.g. a UUID or slug)
+     * @param storage — storage backend; defaults to `InMemoryStorage`
+     */
+    constructor(roomId: string, storage?: StorageProtocol);
+    /**
+     * Connect a participant and return their channel.
+     */
+    connect(participantId: string, name: string, options?: {
+        type?: ParticipantType;
+        identifier?: string;
+        subscribe?: Set<EventCategory>;
+        silent?: boolean;
+        authority?: AuthorityLevel;
+    }): Promise<Channel>;
+    /**
+     * Observe all room events without being a participant.
+     *
+     * Returns a channel that receives every event — broadcasts AND targeted
+     * @mention events directed at other participants. Observers do NOT appear
+     * in `listParticipants()` and do not emit join/leave presence events,
+     * since they are not participants.
+     *
+     * Disconnect via `observer.disconnect()` when done.
+     *
+     * @example
+     * const observer = room.observe();
+     * for await (const event of observer) {
+     *   // sees everything, including mentions for other participants
+     * }
+     */
+    observe(): Channel;
+    /**
+     * Paginate messages, newest-first. Pass the returned `next_cursor` to get
+     * the next (older) page.
+     */
+    listMessages(limit?: number, cursor?: string | null): Promise<PaginatedResult<Message>>;
+    /**
+     * Full-text search across message content, newest-first.
+     * `query` is matched case-insensitively against message content.
+     */
+    searchMessages(query: string, limit?: number, cursor?: string | null): Promise<PaginatedResult<Message>>;
+    /** All currently connected participants (including agents). Observers excluded. */
+    listParticipants(): Participant[];
+    /**
+     * Paginate room events, newest-first.
+     * `category` optionally filters to one EventCategory.
+     */
+    listEvents(category?: EventCategory | null, limit?: number, cursor?: string | null): Promise<PaginatedResult<RoomEvent>>;
+    /** Look up a single message by ID. Returns null if not found. */
+    getMessage(id: string): Promise<Message | null>;
+    /** Update a participant's authority level at runtime. */
+    setParticipantAuthority(participantId: string, authority: AuthorityLevel): boolean;
+    /**
+     * @internal
+     * Store a message, broadcast MessageSentEvent, and fire MentionedEvents.
+     *
+     * @mention scanning: looks for `@token` patterns in content and matches
+     * against each connected participant's `identifier` and display `name`
+     * (case-insensitive). Fires a `MentionedEvent` for each match, delivered
+     * to the mentioned participant AND all observers.
+     */
+    _handleMessage(message: Message): Promise<void>;
+    /**
+     * @internal
+     * Send a ping to a participant. Creates a PingedEvent delivered to the
+     * target's channel and all observers (same routing as MentionedEvent).
+     */
+    _handlePing(senderId: string, senderName: string, targetId: string): Promise<void>;
+    /** @internal Store and broadcast an activity event. */
+    _handleEvent(event: RoomEvent): Promise<void>;
+    /** @internal Remove a channel and optionally broadcast ParticipantLeftEvent. */
+    _disconnectChannel(channel: Channel, silent?: boolean): Promise<void>;
+    private _storeAndBroadcast;
+    private _broadcast;
+    /**
+     * Scan message content for `@token` patterns and return matching participant IDs.
+     * Matches against both `identifier` (e.g. `@my-agent`) and display `name` (e.g. `@Alice`).
+     * Case-insensitive. Deduplicates — each participant appears at most once.
+     */
+    private _detectMentions;
+}
+
+export { type Attachment as A, Channel as C, EventCategory as E, InMemoryStorage as I, type Message as M, type Participant as P, type RoomEvent as R, type StatusChangedEvent as S, type ToolUseEvent as T, type PaginatedResult as a, Room as b, type ParticipantType as c, type AuthorityLevel as d, type ActivityEvent as e, type ContextCompactedEvent as f, EVENT_ROLE as g, type EventRole as h, type MentionedEvent as i, type MessageDeletedEvent as j, type MessageEditedEvent as k, MessageSchema as l, type MessageSentEvent as m, type ParticipantJoinedEvent as n, type ParticipantLeftEvent as o, type ReactionAddedEvent as p, type ReactionRemovedEvent as q, type StorageProtocol as r, createEvent as s };