@gorlitzer-labs/apiary 1.13.3

package/dist/agent/index.d.ts

@@ -0,0 +1,689 @@
+import { P as Participant, M as Message, a as PaginatedResult, E as EventCategory, R as RoomEvent, A as Attachment, b as Room, C as Channel, c as ParticipantType, d as AuthorityLevel } from '../index-Dp3QSGog.js';
+import 'zod';
+
+/**
+ * Uniform interface for reading/writing room data.
+ *
+ * Implemented by:
+ * - `LocalRoomDataSource` — wraps a Room + Channel for in-process access
+ * - `RemoteRoomDataSource` — wraps HTTP calls to a stoop server (Phase 5)
+ */
+interface RoomDataSource {
+    readonly roomId: string;
+    /** The agent's own participant ID in this room. Used for whisper filtering. */
+    readonly selfId: string;
+    listParticipants(): Participant[];
+    getMessage(id: string): Promise<Message | null>;
+    searchMessages(query: string, limit?: number, cursor?: string | null): Promise<PaginatedResult<Message>>;
+    getMessages(limit?: number, cursor?: string | null): Promise<PaginatedResult<Message>>;
+    getEvents(category?: EventCategory | null, limit?: number, cursor?: string | null): Promise<PaginatedResult<RoomEvent>>;
+    sendMessage(content: string, replyToId?: string, image?: {
+        url: string;
+        mimeType: string;
+        sizeBytes: number;
+    } | null, attachments?: Attachment[], recipients?: string[]): Promise<Message>;
+    emitEvent?(event: RoomEvent): Promise<void>;
+}
+/**
+ * LocalRoomDataSource — wraps a Room + Channel for in-process access.
+ *
+ * Used by app-path consumers (ClaudeSession, LangGraphSession) and the
+ * CLI server's EventProcessor. Transparent — all calls delegate directly
+ * to the Room and Channel.
+ */
+declare class LocalRoomDataSource implements RoomDataSource {
+    private _room;
+    private _channel;
+    constructor(_room: Room, _channel: Channel);
+    get roomId(): string;
+    get selfId(): string;
+    /** Direct access to the underlying Room (for backward compat / internal use). */
+    get room(): Room;
+    /** Direct access to the underlying Channel (for backward compat / internal use). */
+    get channel(): Channel;
+    listParticipants(): Participant[];
+    getMessage(id: string): Promise<Message | null>;
+    searchMessages(query: string, limit?: number, cursor?: string | null): Promise<PaginatedResult<Message>>;
+    getMessages(limit?: number, cursor?: string | null): Promise<PaginatedResult<Message>>;
+    getEvents(category?: EventCategory | null, limit?: number, cursor?: string | null): Promise<PaginatedResult<RoomEvent>>;
+    sendMessage(content: string, replyToId?: string, image?: {
+        url: string;
+        mimeType: string;
+        sizeBytes: number;
+    } | null, attachments?: Attachment[], recipients?: string[]): Promise<Message>;
+    emitEvent(event: RoomEvent): Promise<void>;
+}
+
+/**
+ * Shared interfaces for apiary agent infrastructure.
+ *
+ * Two layers:
+ *
+ *   EventProcessor  ──deliver()──►  Consumer (tmux, HTTP API, etc.)
+ *
+ * EventProcessor owns the event loop, engagement, formatting.
+ * Consumers own LLM delivery, MCP servers, compaction, stats.
+ */
+
+/**
+ * A structured content item delivered to the consumer.
+ *
+ * Text parts carry formatted event text; image parts carry the URL of an
+ * attached image so vision-capable consumers can see it natively.
+ */
+type ContentPart = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    url: string;
+};
+/**
+ * A resolved room connection: the data source, the room's display name,
+ * and optional direct room/channel references for backward compatibility.
+ *
+ * Tool handlers and EventProcessor use `dataSource` for all data access.
+ * Direct `room`/`channel` access is kept for app-path consumers that need it.
+ */
+interface RoomConnection {
+    dataSource: RoomDataSource;
+    /** Present for local (app-path) rooms; absent for remote rooms. */
+    room?: Room;
+    /** Present for local (app-path) rooms; absent for remote rooms. */
+    channel?: Channel;
+    name: string;
+}
+/**
+ * Maps room names (and identifiers) to their live connections.
+ *
+ * Implemented by `EventProcessor`. Tool handlers and sessions receive a
+ * `RoomResolver` so they can look up rooms by the names the LLM uses.
+ */
+interface RoomResolver {
+    /** Resolve a room by display name, identifier slug, or room ID. Returns null if unknown. */
+    resolve(roomName: string): RoomConnection | null;
+    /** List all currently connected rooms with metadata. */
+    listAll(): Array<{
+        name: string;
+        roomId: string;
+        identifier?: string;
+        mode: string;
+        participantCount: number;
+        lastMessage?: string;
+    }>;
+}
+/** Callbacks that bridge the session to the EventProcessor. */
+interface ProcessorBridge {
+    isEventSeen?: (eventId: string) => boolean;
+    markEventsSeen?: (eventIds: string[]) => void;
+    assignRef?: (messageId: string) => string;
+    resolveRef?: (ref: string) => string | undefined;
+    onContextCompacted?: () => void;
+    onToolUse?: (toolName: string, status: "started" | "completed") => void;
+}
+/** Subset of ProcessorBridge used by tool handlers and MCP server. */
+type ToolHandlerOptions = Pick<ProcessorBridge, "isEventSeen" | "markEventsSeen" | "assignRef" | "resolveRef">;
+
+/** Event formatting and mode descriptions for apiary agents. */
+
+/** Short 4-char ref for a message ID, used in transcripts. */
+declare function messageRef(messageId: string): string;
+/** Format a participant as a labeled name: "[human] Alice" or "[agent] Quinn". */
+declare function participantLabel(p: Participant | null, fallback?: string): string;
+/** Convert ContentPart[] back to a plain string (for trace logs and stats). */
+declare function contentPartsToString(parts: ContentPart[]): string;
+/**
+ * Format a typed event as ContentPart[] for the LLM session.
+ * Returns null for events that shouldn't be sent to the LLM (noise).
+ *
+ * Compact one-liner format:
+ *   Messages:  [14:23:01] #3847 [lobby] Alice: hey everyone
+ *   Replies:   [14:23:01] #9102 [lobby] Alice (→ #3847 Bob): good point
+ *   Mentions:  [14:23:01] #5521 [lobby] ⚡ Alice: @bot what do you think?
+ *   Joined:    [14:23:01] [lobby] + Alice joined
+ *   Left:      [14:23:15] [lobby] - Bob left
+ *   Reactions:  [14:23:20] [lobby] Alice reacted ❤️ to #3847
+ */
+declare function formatEvent(event: RoomEvent, resolveParticipant: (id: string) => Participant | null, replyContext?: {
+    senderName: string;
+    content: string;
+} | null, roomLabel?: string, reactionTarget?: {
+    senderName: string;
+    content: string;
+    isSelf: boolean;
+} | null, assignRef?: (messageId: string) => string): ContentPart[] | null;
+
+/**
+ * Engagement — controls which room events trigger LLM evaluation.
+ *
+ * # Overview
+ *
+ * Every event that reaches an agent is classified into one of three dispositions:
+ * - "trigger"  — evaluate now (start an LLM call)
+ * - "content"  — buffer as context; deliver to LLM on the next trigger
+ * - "drop"     — ignore entirely (not delivered to LLM)
+ *
+ * The `EngagementStrategy` interface defines this contract. Implement it to
+ * customize when your agent responds. The built-in `StoopsEngagement` provides
+ * a 7-mode system; `classifyEvent()` is a standalone convenience function
+ * using the same logic.
+ *
+ * # Built-in modes (StoopsEngagement / classifyEvent)
+ *
+ * Active modes (agent evaluates on matching messages):
+ * - "everyone"  — all messages trigger evaluation
+ * - "people"    — only messages from human participants trigger evaluation
+ * - "agents"    — only messages from other agents trigger evaluation
+ * - "fight"     — all messages trigger (novelty roast mode)
+ *
+ * Standby modes (agent only wakes on @mentions):
+ * - "standby-everyone" — any @mention wakes the agent
+ * - "standby-people"   — only @mentions from humans wake the agent
+ * - "standby-agents"   — only @mentions from other agents wake the agent
+ *
+ * # Classification rules (in order)
+ *
+ * 1. Internal events (bookkeeping: edits, deletes, status changes, agent
+ *    activity) → always drop
+ * 2. Self-sent events → drop (the agent ignores its own activity).
+ *    Exception: mentions are not self-dropped — a standby agent should wake
+ *    if it is @mentioned, even if the mention event's participant_id is itself.
+ * 3. Standby modes: only @mentions directed at the agent from a matching
+ *    sender → trigger; everything else → drop.
+ * 4. Active modes, @mention → drop (the MessageSent event already carries the
+ *    @mention text; delivering both would be redundant).
+ * 5. Active modes, message from matching sender → trigger
+ * 6. Active modes, message from non-matching sender → content (buffered context)
+ * 7. Active modes, ambient event (join/leave/reaction) → content
+ */
+
+/**
+ * The outcome of classifying an event for a given agent.
+ *
+ * - "trigger" — run an LLM evaluation now
+ * - "content" — buffer as context; include with the next evaluation
+ * - "drop"    — discard; never shown to the LLM
+ */
+type EventDisposition = "trigger" | "content" | "drop";
+/**
+ * Engagement strategy — decides which events trigger LLM evaluation.
+ *
+ * Implement this to customize when your agent responds. The runtime calls
+ * `classify()` for every incoming event and acts on the returned disposition.
+ *
+ * @example
+ * // Respond to everything:
+ * class AlwaysEngage implements EngagementStrategy {
+ *   classify(event, roomId, selfId) {
+ *     if (event.participant_id === selfId) return "drop";
+ *     return "trigger";
+ *   }
+ * }
+ */
+interface EngagementStrategy {
+    /**
+     * Classify a room event for this agent.
+     *
+     * @param event      — the room event to classify
+     * @param roomId     — the room the event came from
+     * @param selfId     — the agent's own participant ID (to drop self-events)
+     * @param senderType — "human" or "agent" for the event's sender
+     * @param senderId   — participant ID of the sender. For `Mentioned` events,
+     *                     pass `event.message.sender_id` (who wrote the mention),
+     *                     not `event.participant_id` (who was mentioned).
+     */
+    classify(event: RoomEvent, roomId: string, selfId: string, senderType: ParticipantType, senderId: string): EventDisposition;
+    /**
+     * Return the current engagement mode for a room.
+     *
+     * Optional — strategies that don't use named modes may omit this.
+     * The runtime falls back to `"everyone"` when absent.
+     */
+    getMode?(roomId: string): EngagementMode;
+    /**
+     * Update the engagement mode for a room.
+     *
+     * Optional — called by the runtime when a room connects with an initial mode
+     * or when the user changes the mode at runtime. Strategies that don't use
+     * named modes may omit this; the call will be silently ignored.
+     */
+    setMode?(roomId: string, mode: EngagementMode): void;
+    /**
+     * Called when a room is disconnected from the runtime.
+     *
+     * Optional — use this for cleanup, e.g. removing per-room state that is
+     * no longer needed. Strategies with no per-room state may omit this.
+     */
+    onRoomDisconnected?(roomId: string): void;
+}
+type EngagementMode = "people" | "agents" | "everyone" | "fight" | "standby-people" | "standby-agents" | "standby-everyone";
+/**
+ * StoopsEngagement — the built-in engagement strategy.
+ *
+ * Implements the 7-mode system: 4 active modes (everyone/people/agents/fight)
+ * and 3 standby modes that only wake on @mentions. Maintains per-room mode
+ * state internally.
+ *
+ * @example
+ * const engagement = new StoopsEngagement("people");
+ * engagement.setMode("room-1", "agents");
+ * engagement.classify(event, "room-1", selfId, "human", senderId);
+ */
+declare class StoopsEngagement implements EngagementStrategy {
+    private _modes;
+    private _defaultMode;
+    constructor(defaultMode: EngagementMode);
+    /** Get the engagement mode for a room. Falls back to the default mode. */
+    getMode(roomId: string): EngagementMode;
+    /** Set the engagement mode for a room. */
+    setMode(roomId: string, mode: EngagementMode): void;
+    /** Called when a room is disconnected. Removes the room's mode so it doesn't linger. */
+    onRoomDisconnected(roomId: string): void;
+    classify(event: RoomEvent, roomId: string, selfId: string, senderType: ParticipantType, senderId: string): EventDisposition;
+}
+/**
+ * Classify a room event for an agent with the given engagement mode.
+ *
+ * Pure function — no state, no side effects, no SDK dependency.
+ * Uses the same classification logic as `StoopsEngagement` but takes all
+ * parameters explicitly. Useful for one-off classification or testing.
+ *
+ * @param event                — the event to classify
+ * @param mode                 — the agent's current engagement mode for this room
+ * @param selfId               — the agent's own participant ID (to drop self-events)
+ * @param senderType           — type of the participant who caused the event
+ * @param senderId             — participant ID of the sender.
+ *                               For `Mentioned` events, pass `event.message.sender_id`
+ *                               (who wrote the mention), not `event.participant_id`
+ *                               (who was mentioned).
+ */
+declare function classifyEvent(event: RoomEvent, mode: EngagementMode, selfId: string, senderType: ParticipantType, senderId: string): EventDisposition;
+
+/** EventMultiplexer — merges N channel async streams into one labeled stream. */
+
+interface LabeledEvent {
+    roomId: string;
+    roomName: string;
+    event: RoomEvent;
+}
+/**
+ * Merges events from multiple channels into a single async iterable stream.
+ * Each event is labeled with its source room's ID and name.
+ *
+ * Channels can be added/removed while the multiplexer is running.
+ */
+declare class EventMultiplexer {
+    private _queue;
+    private _waiters;
+    private _channels;
+    private _closed;
+    private _closeResolve;
+    addChannel(roomId: string, roomName: string, channel: Channel): void;
+    removeChannel(roomId: string): void;
+    close(): void;
+    private _listenLoop;
+    private _push;
+    [Symbol.asyncIterator](): AsyncIterator<LabeledEvent>;
+}
+
+/**
+ * EventProcessor — core event loop for apiary agents.
+ *
+ * Owns: engagement classification, content buffering, event formatting,
+ * ref map, room connections, mode management. Does NOT own: LLM sessions,
+ * MCP servers, compaction hooks, stats tracking.
+ *
+ * Delivery is pluggable — pass a `deliver` callback to `run()`.
+ * The callback receives formatted ContentPart[] and does whatever the
+ * consumer needs (Claude SDK query, LangGraph injection, tmux send-keys).
+ */
+
+interface EventProcessorOptions {
+    /** Engagement mode when no per-room override is set. */
+    defaultMode?: EngagementMode;
+    /** Custom engagement strategy. Defaults to StoopsEngagement. */
+    engagement?: EngagementStrategy;
+    /** The agent's own stable identifier slug (e.g. "my-agent"). */
+    selfIdentifier?: string;
+    /** Called when engagement mode changes for a room. */
+    onModeChange?: (roomId: string, roomName: string, mode: EngagementMode) => void;
+    /** Called before each delivery. Return false to skip. */
+    preQuery?: () => Promise<boolean>;
+}
+/**
+ * What an agent runtime observed on its CLI's screen, as reported to the room.
+ *
+ * Deliberately coarser than each bridge's internal TUI states: the room only
+ * needs to distinguish "getting on with it" from "stuck until a human acts",
+ * because those look identical from the outside and only one of them resolves
+ * by waiting.
+ */
+type AgentActivityState = "idle" | "working" | "blocked";
+declare class EventProcessor implements RoomResolver {
+    private _participantId;
+    private _participantName;
+    private _options;
+    private _engagement;
+    private _deliver;
+    private _multiplexer;
+    private _registry;
+    private _buffer;
+    private _tracker;
+    private _processing;
+    private _eventQueue;
+    private _stopped;
+    private _currentContextRoomId;
+    private _log;
+    private _refMap;
+    private _injectBuffer;
+    /** Per-room participant IDs (for multi-server CLI agents where each server assigns a different ID). */
+    private _roomSelfIds;
+    constructor(participantId: string, participantName: string, options?: EventProcessorOptions);
+    get participantId(): string;
+    set participantId(id: string);
+    get participantName(): string;
+    get currentContextRoomId(): string | null;
+    /** Set a room-specific participant ID (for multi-server CLI agents). */
+    setRoomParticipantId(roomId: string, participantId: string): void;
+    /** Get the effective selfId for a room — room-specific if set, otherwise the global one. */
+    getSelfIdForRoom(roomId: string): string;
+    assignRef(messageId: string): string;
+    resolveRef(ref: string): string | undefined;
+    isEventSeen(eventId: string): boolean;
+    markEventsSeen(eventIds: string[]): void;
+    drainInjectBuffer(): ContentPart[][] | null;
+    /**
+     * Called by the consumer when context was compacted.
+     * Clears seen-event cache and ref map so catch_up returns full history.
+     */
+    onContextCompacted(): void;
+    /**
+     * Called by the consumer when a tool call starts or completes.
+     * Routes ToolUseEvent to the room that triggered the current evaluation.
+     */
+    emitToolUse(toolName: string, status: "started" | "completed"): void;
+    resolve(roomName: string): RoomConnection | null;
+    listAll(): Array<{
+        name: string;
+        roomId: string;
+        identifier?: string;
+        mode: string;
+        participantCount: number;
+        lastMessage?: string;
+    }>;
+    /**
+     * Push a live status label ("Sautéed for 12s", "Compacting…", null=idle)
+     * to every connected REMOTE room (i.e. CLI-path agents talking to an
+     * apiary HTTP server). Local app-path connections are skipped — they don't
+     * have a /activity HTTP endpoint to hit.
+     *
+     * Called from the CLI runtime's tmux poll loop. Best-effort: failures are
+     * swallowed so a flaky network never crashes the agent.
+     */
+    broadcastActivity(label: string | null, state?: AgentActivityState): Promise<void>;
+    /**
+     * Push token usage + last-turn context size to every connected REMOTE
+     * room so the room TUI can show per-agent context size and roll up a
+     * room total. Mirrors broadcastActivity — same best-effort semantics.
+     */
+    broadcastMetrics(metrics: {
+        input_tokens: number;
+        output_tokens: number;
+        cache_read_tokens: number;
+        cache_create_tokens: number;
+        last_ctx_tokens: number;
+        model: string;
+    }): Promise<void>;
+    connectRoom(room: Room, roomName: string, mode?: EngagementMode, identifier?: string): Promise<void>;
+    /**
+     * Connect a remote room via a RoomDataSource (no local Room/Channel).
+     *
+     * Used by the client-side agent runtime to register rooms that are
+     * accessed over HTTP. Events come from an external source (SSE multiplexer)
+     * passed to run(), not from the internal EventMultiplexer.
+     */
+    connectRemoteRoom(dataSource: RoomDataSource, roomName: string, mode?: EngagementMode, identifier?: string): void;
+    /** Disconnect a remote room (by room ID). */
+    disconnectRemoteRoom(roomId: string): void;
+    disconnectRoom(roomId: string): Promise<void>;
+    getModeForRoom(roomId: string): EngagementMode;
+    setModeForRoom(roomId: string, mode: EngagementMode, notifyAgent?: boolean): void;
+    getLog(): RoomEvent[];
+    /**
+     * Start the event loop.
+     *
+     * @param deliver — callback that receives formatted content and delivers
+     *   it to the agent. This is the consumer's responsibility. The function
+     *   should block until delivery is complete (e.g., LLM evaluation finished).
+     * @param eventSource — optional external event source (e.g. SseMultiplexer).
+     *   If provided, events are consumed from this instead of the internal
+     *   EventMultiplexer. Used by the client-side agent runtime.
+     * @param initialParts — optional content to deliver before entering the
+     *   event loop. Used by the runtime to deliver auto-join confirmation.
+     */
+    run(deliver: (parts: ContentPart[]) => Promise<void>, eventSource?: AsyncIterable<LabeledEvent>, initialParts?: ContentPart[]): Promise<void>;
+    stop(): Promise<void>;
+    buildFullCatchUp(): Promise<ContentPart[]>;
+    private _buildFullCatchUp;
+    private _handleLabeledEvent;
+    private _processTrigger;
+    private _resolveParticipantForRoom;
+    private _resolveReplyContext;
+    private _resolveReactionTarget;
+    private _formatForLLM;
+    private _processRaw;
+}
+
+/** What the caller is waiting for. */
+type WaitTarget = "idle" | "blocked" | "working" | "change";
+
+/**
+ * Runtime MCP server — local MCP proxy for the client-side agent runtime.
+ *
+ * Claude Code / OpenCode connects to this local server. Tool calls are routed
+ * to the right apiary server via the RoomResolver (which maps room names to
+ * RemoteRoomDataSource instances).
+ *
+ * Tools:
+ *   Always present:
+ *     apiary__catch_up(room?) — with room: room catch-up. Without: list rooms + pending invites.
+ *     apiary__search_by_text(room, query, count?, cursor?)
+ *     apiary__search_by_message(room, ref, direction?, count?)
+ *     apiary__send_message(room, content, reply_to?)
+ *     apiary__set_mode(room, mode)
+ *     apiary__join_room(url, alias?)
+ *     apiary__leave_room(room)
+ *
+ *   With --admin flag:
+ *     apiary__admin__set_mode_for(room, participant, mode)
+ *     apiary__admin__kick(room, participant)
+ */
+
+interface JoinRoomResult {
+    success: boolean;
+    error?: string;
+    roomName?: string;
+    agentName?: string;
+    authority?: string;
+    mode?: string;
+    personName?: string;
+    participants?: Array<{
+        name: string;
+        authority: string;
+    }>;
+    recentLines?: string[];
+    /** Room rules — surfaced in the join response so the agent sees them on entry. */
+    rules?: string[];
+}
+interface RuntimeMcpServerOptions {
+    resolver: RoomResolver;
+    toolOptions: ToolHandlerOptions;
+    /**
+     * Server-granted authority for this agent's session. Drives which admin /
+     * product_owner tools are exposed. When undefined or "member"/"guest", only
+     * non-privileged tools are registered. Updated after each `join_room`
+     * because the agent's tier can vary per room.
+     */
+    authority?: AuthorityLevel;
+    /** Called when the agent requests joining a new room mid-session. */
+    onJoinRoom?: (url: string, alias?: string, name?: string) => Promise<JoinRoomResult>;
+    /** Called when the agent requests leaving a room. */
+    onLeaveRoom?: (room: string) => Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /** Called when the agent changes its own mode. */
+    onSetMode?: (room: string, mode: string) => Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /** Called when the agent pings a participant for a status check. */
+    onPing?: (room: string, participant: string) => Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    onWaitForAgent?: (room: string, participant: string, until?: WaitTarget, timeoutSec?: number) => Promise<{
+        success: boolean;
+        message?: string;
+        error?: string;
+    }>;
+    /** Called for admin set-mode-for. */
+    onAdminSetModeFor?: (room: string, participant: string, mode: string) => Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /** Called for admin kick. */
+    onAdminKick?: (room: string, participant: string) => Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /** Called for admin mute (demote to guest). */
+    onAdminMute?: (room: string, participant: string) => Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /** Called for admin unmute (restore to member). */
+    onAdminUnmute?: (room: string, participant: string) => Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /** Called for admin promote (elevate to product_owner). */
+    onAdminPromote?: (room: string, participant: string) => Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /** Called for admin demote (drop product_owner back to member). */
+    onAdminDemote?: (room: string, participant: string) => Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+}
+interface RuntimeMcpServer {
+    url: string;
+    stop: () => Promise<void>;
+}
+/**
+ * Create a runtime MCP server on a random localhost port (HTTP transport).
+ * Returns the URL for --mcp-config and a stop function.
+ */
+declare function createRuntimeMcpServer(opts: RuntimeMcpServerOptions): Promise<RuntimeMcpServer>;
+
+/**
+ * RefMap — bidirectional map between short decimal refs and full message UUIDs.
+ *
+ * Why 4 digits: a ref like #3847 tokenizes to 1–2 tokens in most LLMs, while a
+ * raw UUID (a1b2c3d4-e5f6-...) burns 8–12 tokens for no benefit. Since refs
+ * appear on every message in transcripts and tool output, the savings compound.
+ *
+ * 10,000 unique refs per cycle is far more than an LLM context window can hold
+ * (a 200k-token window fits ~2000 messages at most). The map is cleared on every
+ * context compaction, so overflow is essentially impossible in practice. If it
+ * does happen, the fallback to a UUID-derived hash still works — just less tidy.
+ *
+ * Uses a linear congruential generator (n * 6337 mod 10000) to produce
+ * non-sequential refs — gcd(6337, 10000) = 1 guarantees a full cycle through
+ * all 10,000 values before any collision.
+ *
+ * @example
+ * const refs = new RefMap();
+ * const ref = refs.assign("msg-uuid-abc");  // "3847"
+ * refs.assign("msg-uuid-abc");              // "3847" (idempotent)
+ * refs.resolve("3847");                     // "msg-uuid-abc"
+ * refs.clear();                             // reset on compaction
+ */
+declare class RefMap {
+    private _counter;
+    private _refToId;
+    private _idToRef;
+    /** Assign a short ref to a message ID. Returns existing ref if already assigned. */
+    assign(messageId: string): string;
+    /** Resolve a ref back to the full message UUID. Returns undefined if unknown. */
+    resolve(ref: string): string | undefined;
+    /** Clear all mappings and reset the counter. Called on context compaction. */
+    clear(): void;
+}
+
+declare class RemoteRoomDataSource implements RoomDataSource {
+    private _serverUrl;
+    private _sessionToken;
+    private _roomId;
+    private _participants;
+    private _selfId;
+    private _selfName;
+    constructor(_serverUrl: string, _sessionToken: string, _roomId: string);
+    /** Set own identity for populating outgoing message stubs. */
+    setSelf(id: string, name: string): void;
+    get roomId(): string;
+    get selfId(): string;
+    get serverUrl(): string;
+    get sessionToken(): string;
+    /** Set the initial participant list (from join response). */
+    setParticipants(participants: Participant[]): void;
+    /** Add a participant (on ParticipantJoined event). */
+    addParticipant(participant: Participant): void;
+    /** Remove a participant (on ParticipantLeft event). */
+    removeParticipant(participantId: string): void;
+    listParticipants(): Participant[];
+    getMessage(id: string): Promise<Message | null>;
+    searchMessages(query: string, limit?: number, cursor?: string | null): Promise<PaginatedResult<Message>>;
+    getMessages(limit?: number, cursor?: string | null): Promise<PaginatedResult<Message>>;
+    getEvents(category?: EventCategory | null, limit?: number, cursor?: string | null): Promise<PaginatedResult<RoomEvent>>;
+    sendMessage(content: string, replyToId?: string, image?: {
+        url: string;
+        mimeType: string;
+        sizeBytes: number;
+    } | null, attachments?: Attachment[], recipients?: string[]): Promise<Message>;
+    emitEvent(event: RoomEvent): Promise<void>;
+}
+
+/**
+ * SseMultiplexer — merges N SSE connections into one labeled event stream.
+ *
+ * Each connection is an HTTP fetch to a stoop server's /events endpoint.
+ * Events are parsed from the SSE `data:` lines and wrapped as LabeledEvents
+ * (same shape as EventMultiplexer output so EventProcessor can consume either).
+ *
+ * Connections can be added/removed while the multiplexer is running.
+ * Each connection has its own AbortController for independent lifecycle.
+ */
+
+declare class SseMultiplexer {
+    private _queue;
+    private _waiters;
+    private _connections;
+    private _closed;
+    /**
+     * Add an SSE connection to a stoop server.
+     * Starts streaming events immediately.
+     */
+    addConnection(serverUrl: string, sessionToken: string, roomName: string, roomId: string): void;
+    /** Remove a connection by room ID. */
+    removeConnection(roomId: string): void;
+    /** Close all connections and signal the iterator to finish. */
+    close(): void;
+    private _sseLoop;
+    private _push;
+    [Symbol.asyncIterator](): AsyncIterator<LabeledEvent>;
+}
+
+export { type ContentPart, type EngagementMode, type EngagementStrategy, type EventDisposition, EventMultiplexer, EventProcessor, type EventProcessorOptions, type LabeledEvent, LocalRoomDataSource, type ProcessorBridge, RefMap, RemoteRoomDataSource, type RoomConnection, type RoomDataSource, type RoomResolver, type RuntimeMcpServer, type RuntimeMcpServerOptions, SseMultiplexer, StoopsEngagement, type ToolHandlerOptions, classifyEvent, contentPartsToString, createRuntimeMcpServer, formatEvent, messageRef, participantLabel };