agent-relay 1.6.0 → 2.0.0

package/dist/daemon/router.js

@@ -1,1333 +0,0 @@
-/**
- * Message router for the agent relay daemon.
- * Handles routing messages between agents, topic subscriptions, and broadcast.
- */
-import { generateId } from '../utils/id-generator.js';
-import { PROTOCOL_VERSION, } from '../protocol/types.js';
-import { routerLog } from '../utils/logger.js';
-import { RateLimiter, NoOpRateLimiter } from './rate-limiter.js';
-import * as crypto from 'node:crypto';
-import { DeliveryTracker, } from './delivery-tracker.js';
-export class Router {
-    storage;
-    channelMembershipStore;
-    connections = new Map(); // connectionId -> Connection
-    agents = new Map(); // agentName -> Connection
-    subscriptions = new Map(); // topic -> Set<agentName>
-    processingAgents = new Map(); // agentName -> processing state
-    registry;
-    crossMachineHandler;
-    deliveryTracker;
-    /** Shadow relationships: primaryAgent -> list of shadow configs */
-    shadowsByPrimary = new Map();
-    /** Reverse lookup: shadowAgent -> primaryAgent (for cleanup) */
-    primaryByShadow = new Map();
-    /** Channel membership: channel -> Set of member names */
-    channels = new Map();
-    /** User entities (human users, not agents) */
-    users = new Map();
-    /** Reverse lookup: member name -> Set of channels they're in */
-    memberChannels = new Map();
-    /**
-     * Agents that are currently being spawned but haven't completed HELLO yet.
-     * Maps agent name to timestamp when spawn started.
-     * Messages sent to these agents will be queued for delivery after HELLO completes.
-     */
-    spawningAgents = new Map();
-    /** Default timeout for processing indicator (30 seconds) */
-    static PROCESSING_TIMEOUT_MS = 30_000;
-    /** Timeout for spawning agent entries (60 seconds) */
-    static SPAWNING_TIMEOUT_MS = 60_000;
-    /** Callback when processing state changes (for real-time dashboard updates) */
-    onProcessingStateChange;
-    /** Rate limiter for per-agent throttling */
-    rateLimiter;
-    constructor(options = {}) {
-        this.storage = options.storage;
-        this.channelMembershipStore = options.channelMembershipStore;
-        this.registry = options.registry;
-        this.onProcessingStateChange = options.onProcessingStateChange;
-        this.crossMachineHandler = options.crossMachineHandler;
-        this.deliveryTracker = new DeliveryTracker({
-            storage: this.storage,
-            delivery: options.delivery,
-            getConnection: (id) => this.connections.get(id),
-        });
-        // Initialize rate limiter (null = disabled)
-        this.rateLimiter = options.rateLimit === null
-            ? new NoOpRateLimiter()
-            : new RateLimiter(options.rateLimit);
-    }
-    /**
-     * Restore channel memberships from persisted storage.
-     */
-    async restoreChannelMemberships() {
-        if (!this.storage && !this.channelMembershipStore)
-            return;
-        try {
-            if (this.channelMembershipStore) {
-                const memberships = await this.channelMembershipStore.loadMemberships();
-                for (const membership of memberships) {
-                    this.handleMembershipUpdate({
-                        channel: membership.channel,
-                        member: membership.member,
-                        action: 'join',
-                    });
-                }
-            }
-            if (this.storage) {
-                const messages = await this.storage.getMessages({ order: 'asc' });
-                for (const msg of messages) {
-                    const channel = msg.to;
-                    const data = msg.data;
-                    const membership = data?._channelMembership;
-                    if (!channel || !membership?.member) {
-                        continue;
-                    }
-                    const action = membership.action ?? 'join';
-                    this.handleMembershipUpdate({
-                        channel,
-                        member: membership.member,
-                        action,
-                    });
-                }
-            }
-        }
-        catch (err) {
-            routerLog.error('Failed to restore channel memberships', { error: String(err) });
-        }
-    }
-    /**
-     * Set or update the cross-machine handler.
-     */
-    setCrossMachineHandler(handler) {
-        this.crossMachineHandler = handler;
-    }
-    /**
-     * Mark an agent as spawning (before HELLO completes).
-     * Messages sent to this agent will be queued for delivery after registration.
-     */
-    markSpawning(agentName) {
-        this.spawningAgents.set(agentName, Date.now());
-        routerLog.info(`Agent marked as spawning: ${agentName}`, {
-            currentSpawning: Array.from(this.spawningAgents.keys()),
-        });
-        // Clean up stale spawning entries
-        this.cleanupStaleSpawning();
-    }
-    /**
-     * Clear the spawning flag for an agent.
-     * Called when agent completes registration or spawn fails.
-     */
-    clearSpawning(agentName) {
-        if (this.spawningAgents.delete(agentName)) {
-            routerLog.debug(`Agent spawning flag cleared: ${agentName}`);
-        }
-    }
-    /**
-     * Check if an agent is currently spawning.
-     */
-    isSpawning(agentName) {
-        const timestamp = this.spawningAgents.get(agentName);
-        if (!timestamp)
-            return false;
-        // Check if spawn has timed out
-        if (Date.now() - timestamp > Router.SPAWNING_TIMEOUT_MS) {
-            this.spawningAgents.delete(agentName);
-            return false;
-        }
-        return true;
-    }
-    /**
-     * Clean up spawning entries older than SPAWNING_TIMEOUT_MS.
-     */
-    cleanupStaleSpawning() {
-        const now = Date.now();
-        for (const [name, timestamp] of this.spawningAgents) {
-            if (now - timestamp > Router.SPAWNING_TIMEOUT_MS) {
-                this.spawningAgents.delete(name);
-                routerLog.debug(`Cleaned up stale spawning entry: ${name}`);
-            }
-        }
-    }
-    /**
-     * Register a connection after successful handshake.
-     */
-    register(connection) {
-        this.connections.set(connection.id, connection);
-        if (connection.agentName) {
-            const isUser = connection.entityType === 'user';
-            if (isUser) {
-                // Handle existing user connection with same name (disconnect old)
-                const existingUser = this.users.get(connection.agentName);
-                if (existingUser && existingUser.id !== connection.id) {
-                    existingUser.close();
-                    this.connections.delete(existingUser.id);
-                }
-                this.users.set(connection.agentName, connection);
-                routerLog.info(`User registered: ${connection.agentName}`);
-            }
-            else {
-                // Handle existing agent connection with same name (disconnect old)
-                const existing = this.agents.get(connection.agentName);
-                if (existing && existing.id !== connection.id) {
-                    existing.close();
-                    this.connections.delete(existing.id);
-                }
-                this.agents.set(connection.agentName, connection);
-                // Clear spawning flag now that agent has completed registration
-                this.clearSpawning(connection.agentName);
-                this.registry?.registerOrUpdate({
-                    name: connection.agentName,
-                    cli: connection.cli,
-                    program: connection.program,
-                    model: connection.model,
-                    task: connection.task,
-                    workingDirectory: connection.workingDirectory,
-                });
-            }
-        }
-    }
-    /**
-     * Unregister a connection.
-     */
-    unregister(connection) {
-        this.connections.delete(connection.id);
-        if (connection.agentName) {
-            const isUser = connection.entityType === 'user';
-            let wasCurrentConnection = false;
-            if (isUser) {
-                const currentUser = this.users.get(connection.agentName);
-                if (currentUser?.id === connection.id) {
-                    this.users.delete(connection.agentName);
-                    wasCurrentConnection = true;
-                }
-            }
-            else {
-                const current = this.agents.get(connection.agentName);
-                if (current?.id === connection.id) {
-                    this.agents.delete(connection.agentName);
-                    wasCurrentConnection = true;
-                }
-            }
-            // Only clean up channel/subscription state if this was the current connection.
-            // If a new connection replaced this one, we don't want to remove channel memberships
-            // that the new connection should inherit.
-            if (wasCurrentConnection) {
-                // Remove from all subscriptions
-                for (const subscribers of this.subscriptions.values()) {
-                    subscribers.delete(connection.agentName);
-                }
-                // Remove from all channels and notify remaining members
-                this.removeFromAllChannels(connection.agentName);
-                // Clean up shadow relationships
-                this.unbindShadow(connection.agentName);
-                // Clear processing state
-                this.clearProcessing(connection.agentName);
-            }
-        }
-        this.clearPendingForConnection(connection.id);
-    }
-    /**
-     * Remove a member from all channels they're in.
-     */
-    removeFromAllChannels(memberName) {
-        const memberChannelSet = this.memberChannels.get(memberName);
-        if (!memberChannelSet)
-            return;
-        for (const channelName of memberChannelSet) {
-            const members = this.channels.get(channelName);
-            if (members) {
-                members.delete(memberName);
-                // Clean up empty channels
-                if (members.size === 0) {
-                    this.channels.delete(channelName);
-                }
-            }
-        }
-        this.memberChannels.delete(memberName);
-    }
-    /**
-     * Subscribe an agent to a topic.
-     */
-    subscribe(agentName, topic) {
-        let subscribers = this.subscriptions.get(topic);
-        if (!subscribers) {
-            subscribers = new Set();
-            this.subscriptions.set(topic, subscribers);
-        }
-        subscribers.add(agentName);
-    }
-    /**
-     * Unsubscribe an agent from a topic.
-     */
-    unsubscribe(agentName, topic) {
-        const subscribers = this.subscriptions.get(topic);
-        if (subscribers) {
-            subscribers.delete(agentName);
-            if (subscribers.size === 0) {
-                this.subscriptions.delete(topic);
-            }
-        }
-    }
-    /**
-     * Bind a shadow agent to a primary agent.
-     * The shadow will receive copies of messages to/from the primary.
-     */
-    bindShadow(shadowAgent, primaryAgent, options = {}) {
-        // Clean up any existing shadow binding for this shadow
-        this.unbindShadow(shadowAgent);
-        const relationship = {
-            shadowAgent,
-            primaryAgent,
-            speakOn: options.speakOn ?? ['EXPLICIT_ASK'],
-            receiveIncoming: options.receiveIncoming ?? true,
-            receiveOutgoing: options.receiveOutgoing ?? true,
-        };
-        // Add to primary's shadow list
-        let shadows = this.shadowsByPrimary.get(primaryAgent);
-        if (!shadows) {
-            shadows = [];
-            this.shadowsByPrimary.set(primaryAgent, shadows);
-        }
-        shadows.push(relationship);
-        // Set reverse lookup
-        this.primaryByShadow.set(shadowAgent, primaryAgent);
-        routerLog.info(`Shadow bound: ${shadowAgent} -> ${primaryAgent}`, { speakOn: relationship.speakOn });
-    }
-    /**
-     * Unbind a shadow agent from its primary.
-     */
-    unbindShadow(shadowAgent) {
-        const primaryAgent = this.primaryByShadow.get(shadowAgent);
-        if (!primaryAgent)
-            return;
-        // Remove from primary's shadow list
-        const shadows = this.shadowsByPrimary.get(primaryAgent);
-        if (shadows) {
-            const updatedShadows = shadows.filter(s => s.shadowAgent !== shadowAgent);
-            if (updatedShadows.length === 0) {
-                this.shadowsByPrimary.delete(primaryAgent);
-            }
-            else {
-                this.shadowsByPrimary.set(primaryAgent, updatedShadows);
-            }
-        }
-        // Remove reverse lookup
-        this.primaryByShadow.delete(shadowAgent);
-        routerLog.info(`Shadow unbound: ${shadowAgent} from ${primaryAgent}`);
-    }
-    /**
-     * Get all shadows for a primary agent.
-     */
-    getShadowsForPrimary(primaryAgent) {
-        return this.shadowsByPrimary.get(primaryAgent) ?? [];
-    }
-    /**
-     * Get the primary agent for a shadow, if any.
-     */
-    getPrimaryForShadow(shadowAgent) {
-        return this.primaryByShadow.get(shadowAgent);
-    }
-    /**
-     * Emit a trigger event for an agent's shadows.
-     * Shadows configured to speakOn this trigger will receive a notification.
-     * @param primaryAgent The agent whose shadows should be notified
-     * @param trigger The trigger event that occurred
-     * @param context Optional context data about the trigger
-     */
-    emitShadowTrigger(primaryAgent, trigger, context) {
-        const shadows = this.shadowsByPrimary.get(primaryAgent);
-        if (!shadows || shadows.length === 0)
-            return;
-        for (const shadow of shadows) {
-            // Check if this shadow is configured to speak on this trigger
-            if (!shadow.speakOn.includes(trigger) && !shadow.speakOn.includes('ALL_MESSAGES')) {
-                continue;
-            }
-            const target = this.agents.get(shadow.shadowAgent);
-            if (!target)
-                continue;
-            // Create a trigger notification envelope
-            const triggerEnvelope = {
-                v: PROTOCOL_VERSION,
-                type: 'SEND',
-                id: generateId(),
-                ts: Date.now(),
-                from: primaryAgent,
-                to: shadow.shadowAgent,
-                payload: {
-                    kind: 'action',
-                    body: `SHADOW_TRIGGER:${trigger}`,
-                    data: {
-                        _shadowTrigger: trigger,
-                        _shadowOf: primaryAgent,
-                        _triggerContext: context,
-                    },
-                },
-            };
-            const deliver = this.createDeliverEnvelope(primaryAgent, shadow.shadowAgent, triggerEnvelope, target);
-            const sent = target.send(deliver);
-            if (sent) {
-                this.trackDelivery(target, deliver);
-                routerLog.debug(`Shadow trigger ${trigger} sent to ${shadow.shadowAgent}`, { primary: primaryAgent });
-                // Set processing state for triggered shadows - they're expected to respond
-                this.setProcessing(shadow.shadowAgent, deliver.id);
-            }
-        }
-    }
-    /**
-     * Check if a shadow should speak based on a specific trigger.
-     */
-    shouldShadowSpeak(shadowAgent, trigger) {
-        const primaryAgent = this.primaryByShadow.get(shadowAgent);
-        if (!primaryAgent)
-            return true; // Not a shadow, can always speak
-        const shadows = this.shadowsByPrimary.get(primaryAgent);
-        if (!shadows)
-            return true;
-        const relationship = shadows.find(s => s.shadowAgent === shadowAgent);
-        if (!relationship)
-            return true;
-        return relationship.speakOn.includes(trigger) || relationship.speakOn.includes('ALL_MESSAGES');
-    }
-    /**
-     * Route a SEND message to its destination(s).
-     */
-    route(from, envelope) {
-        const senderName = from.agentName;
-        if (!senderName) {
-            routerLog.warn('Dropping message - sender has no name');
-            return;
-        }
-        // Check rate limit
-        if (!this.rateLimiter.tryAcquire(senderName)) {
-            routerLog.warn(`Rate limited: ${senderName}`);
-            return;
-        }
-        // Agent is responding - clear their processing state
-        this.clearProcessing(senderName);
-        this.registry?.recordSend(senderName);
-        const to = envelope.to;
-        const topic = envelope.topic;
-        routerLog.info(`Route ${senderName} -> ${to}`, { preview: envelope.payload.body?.substring(0, 50) });
-        if (to === '*') {
-            // Broadcast to all (except sender)
-            this.broadcast(senderName, envelope, topic);
-        }
-        else if (to) {
-            // Direct message
-            this.sendDirect(senderName, to, envelope);
-        }
-        // Route copies to shadows of the sender (outgoing messages)
-        this.routeToShadows(senderName, envelope, 'outgoing');
-        // Route copies to shadows of the recipient (incoming messages)
-        if (to && to !== '*') {
-            this.routeToShadows(to, envelope, 'incoming', senderName);
-        }
-    }
-    /**
-     * Route a copy of a message to shadows of an agent.
-     * @param primaryAgent The primary agent whose shadows should receive the message
-     * @param envelope The original message envelope
-     * @param direction Whether this is an 'incoming' or 'outgoing' message for the primary
-     * @param actualFrom Override the 'from' field (for incoming messages, use original sender)
-     */
-    routeToShadows(primaryAgent, envelope, direction, actualFrom) {
-        const shadows = this.shadowsByPrimary.get(primaryAgent);
-        if (!shadows || shadows.length === 0)
-            return;
-        for (const shadow of shadows) {
-            // Check if shadow wants this direction
-            if (direction === 'incoming' && shadow.receiveIncoming === false)
-                continue;
-            if (direction === 'outgoing' && shadow.receiveOutgoing === false)
-                continue;
-            // Don't send to self
-            if (shadow.shadowAgent === (actualFrom ?? primaryAgent))
-                continue;
-            const target = this.agents.get(shadow.shadowAgent);
-            if (!target)
-                continue;
-            // Create a shadow copy envelope with metadata indicating it's a shadow copy
-            const shadowEnvelope = {
-                ...envelope,
-                payload: {
-                    ...envelope.payload,
-                    data: {
-                        ...envelope.payload.data,
-                        _shadowCopy: true,
-                        _shadowOf: primaryAgent,
-                        _shadowDirection: direction,
-                    },
-                },
-            };
-            const deliver = this.createDeliverEnvelope(actualFrom ?? primaryAgent, shadow.shadowAgent, shadowEnvelope, target);
-            const sent = target.send(deliver);
-            if (sent) {
-                this.trackDelivery(target, deliver);
-                routerLog.debug(`Shadow copy to ${shadow.shadowAgent}`, { direction, primary: primaryAgent });
-                // Note: Don't set processing state for shadow copies - shadow stays passive
-            }
-        }
-    }
-    /**
-     * Send a direct message to a specific agent.
-     *
-     * If the target agent is offline but known (has connected before),
-     * the message is persisted for delivery when the agent reconnects.
-     * This prevents silent message drops during brief disconnections or spawn timing issues.
-     */
-    sendDirect(from, to, envelope) {
-        const target = this.agents.get(to) ?? this.users.get(to);
-        const isUserTarget = target?.entityType === 'user';
-        // If agent not found locally, check if it's on a remote machine
-        if (!target) {
-            const remoteAgent = this.crossMachineHandler?.isRemoteAgent(to);
-            if (remoteAgent) {
-                routerLog.info(`Routing to remote agent: ${to}`, { daemonName: remoteAgent.daemonName });
-                return this.sendToRemoteAgent(from, to, envelope, remoteAgent);
-            }
-            // Also check if it's a remote user (human connected via cloud dashboard)
-            const remoteUser = this.crossMachineHandler?.isRemoteUser?.(to);
-            if (remoteUser) {
-                routerLog.info(`Routing to remote user: ${to}`, { daemonName: remoteUser.daemonName });
-                return this.sendToRemoteAgent(from, to, envelope, remoteUser);
-            }
-            // Check if this is a known agent (has connected before) - queue for later delivery
-            // This prevents message drops during brief disconnections or spawn timing issues
-            if (this.registry?.has(to)) {
-                routerLog.info(`Target "${to}" offline but known, queueing message for delivery on reconnect`);
-                this.persistMessageForOfflineAgent(from, to, envelope);
-                return true; // Message accepted (queued), not dropped
-            }
-            // Check if agent is currently spawning (pre-HELLO) - queue for delivery after registration
-            // This handles the race condition between spawn completion and HELLO handshake
-            const spawning = this.isSpawning(to);
-            routerLog.debug(`Spawning check for "${to}": ${spawning}`, {
-                spawningAgents: Array.from(this.spawningAgents.keys()),
-                hasStorage: !!this.storage,
-            });
-            if (spawning) {
-                routerLog.info(`Target "${to}" is spawning, queueing message for delivery after registration`);
-                this.persistMessageForOfflineAgent(from, to, envelope);
-                return true; // Message accepted (queued), not dropped
-            }
-            routerLog.warn(`Target "${to}" not found and unknown`, { availableAgents: Array.from(this.agents.keys()), spawningAgents: Array.from(this.spawningAgents.keys()) });
-            return false;
-        }
-        const deliver = this.createDeliverEnvelope(from, to, envelope, target);
-        const sent = target.send(deliver);
-        routerLog.info(`Delivered ${from} -> ${to}`, { success: sent, preview: envelope.payload.body?.substring(0, 40) });
-        this.persistDeliverEnvelope(deliver);
-        if (sent) {
-            this.trackDelivery(target, deliver);
-            this.registry?.recordReceive(to);
-            // Only mark AI agents as processing; humans don't need processing indicators
-            if (!isUserTarget) {
-                this.setProcessing(to, deliver.id);
-            }
-        }
-        return sent;
-    }
-    /**
-     * Send a message to an agent on a remote machine via cloud.
-     */
-    sendToRemoteAgent(from, to, envelope, remoteAgent) {
-        if (!this.crossMachineHandler) {
-            routerLog.warn('Cross-machine handler not available');
-            return false;
-        }
-        // Send asynchronously via cloud
-        this.crossMachineHandler.sendCrossMachineMessage(remoteAgent.daemonId, to, from, envelope.payload.body, {
-            topic: envelope.topic,
-            thread: envelope.payload.thread,
-            kind: envelope.payload.kind,
-            data: envelope.payload.data,
-            originalId: envelope.id,
-        }).then((sent) => {
-            if (sent) {
-                routerLog.info(`Cross-machine message sent to ${to}`, { daemonName: remoteAgent.daemonName });
-                // Persist as cross-machine message
-                this.storage?.saveMessage({
-                    id: envelope.id || `cross-${Date.now()}`,
-                    ts: Date.now(),
-                    from,
-                    to,
-                    topic: envelope.topic,
-                    kind: envelope.payload.kind,
-                    body: envelope.payload.body,
-                    data: {
-                        ...envelope.payload.data,
-                        _crossMachine: true,
-                        _targetDaemon: remoteAgent.daemonId,
-                        _targetDaemonName: remoteAgent.daemonName,
-                    },
-                    thread: envelope.payload.thread,
-                    status: 'unread',
-                    is_urgent: false,
-                    is_broadcast: false,
-                }).catch(err => routerLog.error('Failed to persist cross-machine message', { error: String(err) }));
-            }
-            else {
-                routerLog.error(`Failed to send cross-machine message to ${to}`);
-            }
-        }).catch(err => {
-            routerLog.error('Cross-machine send error', { error: String(err) });
-        });
-        // Return true immediately - message is queued
-        return true;
-    }
-    /**
-     * Broadcast to all agents (optionally filtered by topic subscription).
-     */
-    broadcast(from, envelope, topic) {
-        // Build recipients list from both agents and users
-        const recipients = topic
-            ? this.subscriptions.get(topic) ?? new Set()
-            : new Set([...this.agents.keys(), ...this.users.keys()]);
-        for (const recipientName of recipients) {
-            if (recipientName === from)
-                continue; // Don't send to self
-            // Check both agents and users maps (consistent with sendDirect)
-            const target = this.agents.get(recipientName) ?? this.users.get(recipientName);
-            if (target) {
-                const isUserTarget = target.entityType === 'user';
-                const deliver = this.createDeliverEnvelope(from, recipientName, envelope, target);
-                const sent = target.send(deliver);
-                this.persistDeliverEnvelope(deliver, true); // Mark as broadcast
-                if (sent) {
-                    this.trackDelivery(target, deliver);
-                    this.registry?.recordReceive(recipientName);
-                    // Only mark AI agents as processing; humans don't need processing indicators
-                    if (!isUserTarget) {
-                        this.setProcessing(recipientName, deliver.id);
-                    }
-                }
-            }
-        }
-    }
-    /**
-     * Create a DELIVER envelope from a SEND.
-     */
-    createDeliverEnvelope(from, to, original, target) {
-        // Preserve the original 'to' field for broadcasts so agents know to reply to '*'
-        const originalTo = original.to;
-        return {
-            v: PROTOCOL_VERSION,
-            type: 'DELIVER',
-            id: generateId(),
-            ts: Date.now(),
-            from,
-            to,
-            topic: original.topic,
-            payload: original.payload,
-            payload_meta: original.payload_meta,
-            delivery: {
-                seq: target.getNextSeq(original.topic ?? 'default', from),
-                session_id: target.sessionId,
-                originalTo: originalTo !== to ? originalTo : undefined, // Only include if different
-            },
-        };
-    }
-    /**
-     * Persist a delivered message if storage is configured.
-     */
-    persistDeliverEnvelope(envelope, isBroadcast = false) {
-        if (!this.storage)
-            return;
-        this.storage.saveMessage({
-            id: envelope.id,
-            ts: envelope.ts,
-            from: envelope.from ?? 'unknown',
-            to: envelope.to ?? 'unknown',
-            topic: envelope.topic,
-            kind: envelope.payload.kind,
-            body: envelope.payload.body,
-            data: envelope.payload.data,
-            payloadMeta: envelope.payload_meta,
-            thread: envelope.payload.thread,
-            deliverySeq: envelope.delivery.seq,
-            deliverySessionId: envelope.delivery.session_id,
-            sessionId: envelope.delivery.session_id,
-            status: 'unread',
-            is_urgent: false,
-            is_broadcast: isBroadcast || envelope.to === '*',
-        }).catch((err) => {
-            routerLog.error('Failed to persist message', { error: String(err) });
-        });
-    }
-    /**
-     * Persist a message for an offline agent.
-     * Called when a message is sent to a known agent that is not currently connected.
-     * The message is marked with _offlineQueued and will be delivered when the agent reconnects.
-     */
-    persistMessageForOfflineAgent(from, to, envelope) {
-        if (!this.storage) {
-            routerLog.warn('Cannot queue offline message: no storage configured');
-            return;
-        }
-        routerLog.info(`Persisting offline message for "${to}"`, {
-            from,
-            messageId: envelope.id,
-            bodyPreview: envelope.payload.body?.substring(0, 50),
-        });
-        this.storage.saveMessage({
-            id: envelope.id || generateId(),
-            ts: Date.now(),
-            from,
-            to,
-            topic: envelope.topic,
-            kind: envelope.payload.kind,
-            body: envelope.payload.body,
-            data: {
-                ...envelope.payload.data,
-                _offlineQueued: true, // Mark as queued for offline delivery
-                _queuedAt: Date.now(),
-            },
-            payloadMeta: envelope.payload_meta,
-            thread: envelope.payload.thread,
-            status: 'unread', // Unread = pending delivery
-            is_urgent: false,
-            is_broadcast: false,
-        }).catch((err) => {
-            routerLog.error('Failed to persist offline message', { error: String(err), to });
-        });
-    }
-    /**
-     * Deliver pending messages to an agent that just connected.
-     * Queries for unread messages addressed to this agent that were queued while offline.
-     * This handles messages that were sent while the agent was offline.
-     */
-    async deliverPendingMessages(connection) {
-        const agentName = connection.agentName;
-        if (!agentName)
-            return;
-        if (!this.storage?.getMessages)
-            return;
-        try {
-            // Query for unread messages addressed to this agent
-            const pendingMessages = await this.storage.getMessages({
-                to: agentName,
-                unreadOnly: true,
-                order: 'asc', // Deliver oldest first
-            });
-            // Filter to only include offline-queued messages (not already-delivered unacked messages)
-            const offlineMessages = pendingMessages.filter(msg => msg.data?._offlineQueued === true).sort((a, b) => a.ts - b.ts);
-            if (offlineMessages.length === 0)
-                return;
-            routerLog.info(`Delivering ${offlineMessages.length} pending messages to ${agentName}`);
-            for (const msg of offlineMessages) {
-                // Create deliver envelope
-                const deliverEnvelope = {
-                    v: PROTOCOL_VERSION,
-                    type: 'DELIVER',
-                    id: generateId(),
-                    ts: Date.now(),
-                    from: msg.from,
-                    to: agentName,
-                    topic: msg.topic,
-                    payload: {
-                        body: msg.body,
-                        kind: msg.kind,
-                        data: msg.data,
-                        thread: msg.thread,
-                    },
-                    payload_meta: msg.payloadMeta,
-                    delivery: {
-                        seq: connection.getNextSeq(msg.topic ?? 'default', msg.from),
-                        session_id: connection.sessionId,
-                    },
-                };
-                const sent = connection.send(deliverEnvelope);
-                if (sent) {
-                    this.trackDelivery(connection, deliverEnvelope);
-                    this.registry?.recordReceive(agentName);
-                    this.setProcessing(agentName, deliverEnvelope.id);
-                    // Mark original message as delivered (update status)
-                    if (this.storage.updateMessageStatus) {
-                        await this.storage.updateMessageStatus(msg.id, 'read');
-                    }
-                    routerLog.info(`Delivered pending message to ${agentName}`, {
-                        from: msg.from,
-                        preview: msg.body.substring(0, 40),
-                    });
-                }
-                else {
-                    routerLog.warn(`Failed to deliver pending message to ${agentName}`);
-                }
-            }
-        }
-        catch (err) {
-            routerLog.error('Failed to deliver pending messages', { error: String(err), agentName });
-        }
-    }
-    /**
-     * Get list of connected agent names.
-     */
-    getAgents() {
-        return Array.from(this.agents.keys());
-    }
-    /**
-     * Get connection by agent name.
-     */
-    getConnection(agentName) {
-        return this.agents.get(agentName);
-    }
-    /**
-     * Get number of active connections.
-     */
-    get connectionCount() {
-        return this.connections.size;
-    }
-    get pendingDeliveryCount() {
-        return this.deliveryTracker.pendingCount;
-    }
-    /**
-     * Get rate limiter statistics.
-     */
-    getRateLimiterStats() {
-        return this.rateLimiter.getStats();
-    }
-    /**
-     * Reset rate limit for a specific agent (admin operation).
-     */
-    resetRateLimit(agentName) {
-        this.rateLimiter.reset(agentName);
-    }
-    /**
-     * Get list of agents currently processing (thinking).
-     * Returns an object with agent names as keys and processing info as values.
-     */
-    getProcessingAgents() {
-        const result = {};
-        for (const [name, state] of this.processingAgents.entries()) {
-            result[name] = { startedAt: state.startedAt, messageId: state.messageId };
-        }
-        return result;
-    }
-    /**
-     * Check if a specific agent is processing.
-     */
-    isAgentProcessing(agentName) {
-        return this.processingAgents.has(agentName);
-    }
-    /**
-     * Mark an agent as processing (called when they receive a message).
-     */
-    setProcessing(agentName, messageId) {
-        // Clear any existing processing state
-        this.clearProcessing(agentName);
-        const timer = setTimeout(() => {
-            this.clearProcessing(agentName);
-            routerLog.warn(`Processing timeout for ${agentName}`);
-        }, Router.PROCESSING_TIMEOUT_MS);
-        this.processingAgents.set(agentName, {
-            startedAt: Date.now(),
-            messageId,
-            timer,
-        });
-        routerLog.debug(`${agentName} started processing`, { messageId });
-        this.onProcessingStateChange?.();
-    }
-    /**
-     * Clear processing state for an agent (called when they send a message).
-     */
-    clearProcessing(agentName) {
-        const state = this.processingAgents.get(agentName);
-        if (state) {
-            if (state.timer) {
-                clearTimeout(state.timer);
-            }
-            this.processingAgents.delete(agentName);
-            routerLog.debug(`${agentName} finished processing`);
-            this.onProcessingStateChange?.();
-        }
-    }
-    /**
-     * Handle ACK for previously delivered messages.
-     */
-    handleAck(connection, envelope) {
-        const ackId = envelope.payload.ack_id;
-        this.deliveryTracker.handleAck(connection.id, ackId);
-    }
-    /**
-     * Clear pending deliveries for a connection (e.g., on disconnect).
-     */
-    clearPendingForConnection(connectionId) {
-        this.deliveryTracker.clearPendingForConnection(connectionId);
-    }
-    /**
-     * Track a delivery and schedule retries until ACKed or TTL/attempts exhausted.
-     */
-    trackDelivery(target, deliver) {
-        this.deliveryTracker.track(target, deliver);
-    }
-    /**
-     * Broadcast a system message to all connected agents.
-     * Used for system notifications like agent death announcements.
-     */
-    broadcastSystemMessage(message, data) {
-        const envelope = {
-            v: PROTOCOL_VERSION,
-            type: 'SEND',
-            id: generateId(),
-            ts: Date.now(),
-            from: '_system',
-            to: '*',
-            payload: {
-                kind: 'message',
-                body: message,
-                data: {
-                    ...data,
-                    _isSystemMessage: true,
-                },
-            },
-        };
-        // Broadcast to all agents
-        for (const [agentName, connection] of this.agents.entries()) {
-            const deliver = this.createDeliverEnvelope('_system', agentName, envelope, connection);
-            const sent = connection.send(deliver);
-            if (sent) {
-                routerLog.debug(`System broadcast sent to ${agentName}`);
-            }
-        }
-    }
-    /**
-     * Replay any pending (unacked) messages for a resumed session.
-     */
-    async replayPending(connection) {
-        if (!this.storage?.getPendingMessagesForSession || !connection.agentName) {
-            return;
-        }
-        const pending = await this.storage.getPendingMessagesForSession(connection.agentName, connection.sessionId);
-        if (!pending.length)
-            return;
-        routerLog.info(`Replaying ${pending.length} messages to ${connection.agentName}`);
-        for (const msg of pending) {
-            const deliver = {
-                v: PROTOCOL_VERSION,
-                type: 'DELIVER',
-                id: msg.id,
-                ts: msg.ts,
-                from: msg.from,
-                to: msg.to,
-                topic: msg.topic,
-                payload: {
-                    kind: msg.kind,
-                    body: msg.body,
-                    data: msg.data,
-                    thread: msg.thread,
-                },
-                payload_meta: msg.payloadMeta,
-                delivery: {
-                    seq: msg.deliverySeq ?? connection.getNextSeq(msg.topic ?? 'default', msg.from),
-                    session_id: msg.deliverySessionId ?? connection.sessionId,
-                },
-            };
-            const sent = connection.send(deliver);
-            if (sent) {
-                this.trackDelivery(connection, deliver);
-            }
-        }
-    }
-    // ==================== Channel Methods ====================
-    /**
-     * Handle a CHANNEL_JOIN message.
-     * Adds the member to the channel and notifies existing members.
-     * If payload.member is set, adds that member (admin mode).
-     * Otherwise, adds the connection's agent name.
-     */
-    handleChannelJoin(connection, envelope) {
-        // Use payload.member if provided (admin mode), otherwise use connection's name
-        const memberName = envelope.payload.member ?? connection.agentName;
-        if (!memberName) {
-            routerLog.warn('CHANNEL_JOIN from connection without name and no member specified');
-            return;
-        }
-        const channel = envelope.payload.channel;
-        const isAdminJoin = Boolean(envelope.payload.member);
-        // Get or create channel
-        let members = this.channels.get(channel);
-        if (!members) {
-            members = new Set();
-            this.channels.set(channel, members);
-        }
-        // Check if already a member
-        if (members.has(memberName)) {
-            routerLog.debug(`${memberName} already in ${channel}`);
-            return;
-        }
-        // Only notify existing members for non-admin joins (agents joining themselves)
-        // Admin joins are silent to avoid spamming notifications when syncing
-        if (!isAdminJoin) {
-            const existingMembers = members ? Array.from(members) : [];
-            for (const existingMember of existingMembers) {
-                const memberConn = this.getConnectionByName(existingMember);
-                if (memberConn) {
-                    const joinNotification = {
-                        v: PROTOCOL_VERSION,
-                        type: 'CHANNEL_JOIN',
-                        id: generateId(),
-                        ts: Date.now(),
-                        from: memberName,
-                        payload: envelope.payload,
-                    };
-                    memberConn.send(joinNotification);
-                }
-            }
-        }
-        const added = this.addChannelMember(channel, memberName, { persist: true });
-        if (!added) {
-            routerLog.debug(`${memberName} already in ${channel}`);
-            return;
-        }
-        routerLog.info(`${memberName} joined ${channel} (${this.channels.get(channel)?.size ?? 0} members)${isAdminJoin ? ' [admin]' : ''}`);
-    }
-    /**
-     * Handle a CHANNEL_LEAVE message.
-     * Removes the member from the channel and notifies remaining members.
-     * If payload.member is provided, removes that member instead (admin mode).
-     */
-    handleChannelLeave(connection, envelope) {
-        // Use payload.member if provided (admin mode), otherwise use connection's name
-        const memberName = envelope.payload.member ?? connection.agentName;
-        if (!memberName) {
-            routerLog.warn('CHANNEL_LEAVE from connection without name and no member specified');
-            return;
-        }
-        const channel = envelope.payload.channel;
-        const isAdminRemove = Boolean(envelope.payload.member);
-        const members = this.channels.get(channel);
-        if (!members || !members.has(memberName)) {
-            routerLog.debug(`${memberName} not in ${channel}, ignoring leave`);
-            return;
-        }
-        const removed = this.removeChannelMember(channel, memberName, { persist: true });
-        if (!removed) {
-            routerLog.debug(`${memberName} not in ${channel}, ignoring leave`);
-            return;
-        }
-        // Only notify remaining members for non-admin removes
-        // Admin removes are silent to avoid spamming notifications
-        if (!isAdminRemove) {
-            const remainingMembers = this.channels.get(channel);
-            if (remainingMembers) {
-                for (const remainingMember of remainingMembers) {
-                    const memberConn = this.getConnectionByName(remainingMember);
-                    if (memberConn) {
-                        const leaveNotification = {
-                            v: PROTOCOL_VERSION,
-                            type: 'CHANNEL_LEAVE',
-                            id: generateId(),
-                            ts: Date.now(),
-                            from: memberName,
-                            payload: envelope.payload,
-                        };
-                        memberConn.send(leaveNotification);
-                    }
-                }
-            }
-        }
-        routerLog.info(`${memberName} left ${channel}${isAdminRemove ? ' [admin]' : ''}`);
-    }
-    /**
-     * Route a channel message to all members except the sender.
-     */
-    routeChannelMessage(connection, envelope) {
-        const senderName = connection.agentName;
-        if (!senderName) {
-            routerLog.warn('CHANNEL_MESSAGE from connection without name');
-            return;
-        }
-        const channel = envelope.payload.channel;
-        const members = this.channels.get(channel);
-        routerLog.info(`routeChannelMessage: channel=${channel} sender=${senderName} members=${members ? Array.from(members).join(',') : 'NONE'}`);
-        if (!members) {
-            routerLog.warn(`Message to non-existent channel ${channel} (available channels: ${Array.from(this.channels.keys()).join(', ')})`);
-            return;
-        }
-        // Case-insensitive membership check
-        const senderMemberName = this.findMemberInSet(members, senderName);
-        if (!senderMemberName) {
-            routerLog.warn(`${senderName} not a member of ${channel} (members: ${Array.from(members).join(', ')})`);
-            return;
-        }
-        // Route to all members except the sender (no echo)
-        const allMembers = Array.from(members);
-        routerLog.info(`Routing channel message from ${senderName} to ${channel}`, {
-            totalMembers: allMembers.length,
-            members: allMembers,
-        });
-        let deliveredCount = 0;
-        const undeliveredMembers = [];
-        const connectedAgents = Array.from(this.agents.keys());
-        const connectedUsers = Array.from(this.users.keys());
-        routerLog.info(`Connected entities: agents=[${connectedAgents.join(',')}] users=[${connectedUsers.join(',')}]`);
-        for (const memberName of members) {
-            // Case-insensitive comparison to skip sender
-            if (this.namesMatch(memberName, senderName)) {
-                continue;
-            }
-            const memberConn = this.getConnectionByName(memberName);
-            if (memberConn) {
-                const deliverEnvelope = {
-                    v: PROTOCOL_VERSION,
-                    type: 'CHANNEL_MESSAGE',
-                    id: generateId(),
-                    ts: Date.now(),
-                    from: senderName,
-                    payload: envelope.payload,
-                };
-                const sent = memberConn.send(deliverEnvelope);
-                if (sent) {
-                    deliveredCount++;
-                    routerLog.info(`Delivered to ${memberName} (${memberConn.entityType || 'agent'})`);
-                }
-                else {
-                    routerLog.warn(`Failed to send to ${memberName}`);
-                    undeliveredMembers.push(memberName);
-                }
-            }
-            else {
-                routerLog.warn(`Member ${memberName} is registered in channel but NOT connected to daemon - message not delivered`);
-                undeliveredMembers.push(memberName);
-            }
-        }
-        // Persist channel message
-        this.persistChannelMessage(envelope, senderName);
-        const recipientCount = allMembers.length - 1; // Exclude sender
-        routerLog.info(`${senderName} -> ${channel}: delivered to ${deliveredCount}/${recipientCount} members`);
-        // Log warning if some members didn't receive the message
-        if (undeliveredMembers.length > 0) {
-            routerLog.warn(`Channel message undelivered to: [${undeliveredMembers.join(', ')}] - these agents may need to reconnect to the relay daemon`);
-        }
-    }
-    /**
-     * Persist a channel message to storage.
-     */
-    persistChannelMessage(envelope, from) {
-        if (!this.storage)
-            return;
-        const payloadData = {
-            ...envelope.payload.data,
-            _isChannelMessage: true,
-            _channel: envelope.payload.channel,
-            _mentions: envelope.payload.mentions,
-        };
-        this.storage.saveMessage({
-            id: envelope.id,
-            ts: envelope.ts,
-            from,
-            to: envelope.payload.channel, // Channel name as "to"
-            topic: undefined,
-            kind: 'message',
-            body: envelope.payload.body,
-            data: payloadData,
-            thread: envelope.payload.thread,
-            status: 'unread',
-            is_urgent: false,
-            is_broadcast: true, // Channel messages are effectively broadcasts
-        }).catch((err) => {
-            routerLog.error('Failed to persist channel message', { error: String(err) });
-        });
-    }
-    persistChannelMembership(channel, member, action, opts) {
-        if (this.storage) {
-            this.storage.saveMessage({
-                id: crypto.randomUUID(),
-                ts: Date.now(),
-                from: '__system__',
-                to: channel,
-                topic: undefined,
-                kind: 'state', // membership events stored as state
-                body: `${action}:${member}`,
-                data: {
-                    _channelMembership: {
-                        member,
-                        action,
-                        invitedBy: opts?.invitedBy,
-                    },
-                },
-                status: 'read',
-                is_urgent: false,
-                is_broadcast: true,
-            }).catch((err) => {
-                routerLog.error('Failed to persist channel membership', { error: String(err) });
-            });
-        }
-        if (this.channelMembershipStore) {
-            const persistPromise = action === 'leave'
-                ? this.channelMembershipStore.removeMember(channel, member)
-                : this.channelMembershipStore.addMember(channel, member);
-            persistPromise.catch((err) => {
-                routerLog.error('Failed to sync channel membership to cloud store', {
-                    channel,
-                    member,
-                    action,
-                    error: err instanceof Error ? err.message : String(err),
-                });
-            });
-        }
-    }
-    /**
-     * Get all members of a channel.
-     */
-    getChannelMembers(channel) {
-        const members = this.channels.get(channel);
-        return members ? Array.from(members) : [];
-    }
-    /**
-     * Get all channels.
-     */
-    getChannels() {
-        return Array.from(this.channels.keys());
-    }
-    /**
-     * Get all channels a member is in.
-     */
-    getChannelsForMember(memberName) {
-        const channels = this.memberChannels.get(memberName);
-        return channels ? Array.from(channels) : [];
-    }
-    /**
-     * Check if a name belongs to a user (not an agent).
-     */
-    isUser(name) {
-        return this.users.has(name);
-    }
-    /**
-     * Check if a name belongs to an agent (not a user).
-     */
-    isAgent(name) {
-        return this.agents.has(name);
-    }
-    /**
-     * Get list of connected user names (human users only).
-     */
-    getUsers() {
-        return Array.from(this.users.keys());
-    }
-    /**
-     * Get a connection by name (checks both agents and users).
-     * Uses case-insensitive lookup to handle mismatched casing.
-     */
-    getConnectionByName(name) {
-        // Try exact match first
-        const exact = this.agents.get(name) ?? this.users.get(name);
-        if (exact)
-            return exact;
-        // Fall back to case-insensitive search
-        const lowerName = name.toLowerCase();
-        for (const [key, conn] of this.agents) {
-            if (key.toLowerCase() === lowerName)
-                return conn;
-        }
-        for (const [key, conn] of this.users) {
-            if (key.toLowerCase() === lowerName)
-                return conn;
-        }
-        return undefined;
-    }
-    /**
-     * Check if a member is in a Set (case-insensitive).
-     * Returns the actual stored name if found, undefined otherwise.
-     */
-    findMemberInSet(members, name) {
-        // Try exact match first
-        if (members.has(name))
-            return name;
-        // Fall back to case-insensitive search
-        const lowerName = name.toLowerCase();
-        for (const member of members) {
-            if (member.toLowerCase() === lowerName)
-                return member;
-        }
-        return undefined;
-    }
-    /**
-     * Check if two names match (case-insensitive).
-     */
-    namesMatch(a, b) {
-        return a.toLowerCase() === b.toLowerCase();
-    }
-    /**
-     * Auto-join a member to a channel without notifications.
-     * Used for default channel membership (e.g., #general).
-     * @param memberName - The agent or user name to add
-     * @param channel - The channel to join (e.g., '#general')
-     */
-    autoJoinChannel(memberName, channel, options) {
-        // Get or create channel
-        let members = this.channels.get(channel);
-        if (!members) {
-            members = new Set();
-            this.channels.set(channel, members);
-        }
-        // Check if already a member
-        const added = this.addChannelMember(channel, memberName, { persist: options?.persist });
-        if (added) {
-            routerLog.debug(`Auto-joined ${memberName} to ${channel}`);
-        }
-    }
-    addChannelMember(channel, memberName, options) {
-        let members = this.channels.get(channel);
-        if (!members) {
-            members = new Set();
-            this.channels.set(channel, members);
-        }
-        // Case-insensitive check for existing membership
-        const existingMember = this.findMemberInSet(members, memberName);
-        if (existingMember) {
-            return false;
-        }
-        members.add(memberName);
-        const memberChannelSet = this.memberChannels.get(memberName) ?? new Set();
-        memberChannelSet.add(channel);
-        this.memberChannels.set(memberName, memberChannelSet);
-        if (options?.persist ?? true) {
-            this.persistChannelMembership(channel, memberName, 'join');
-        }
-        return true;
-    }
-    removeChannelMember(channel, memberName, options) {
-        const members = this.channels.get(channel);
-        if (!members) {
-            return false;
-        }
-        // Case-insensitive lookup to find actual stored name
-        const actualMemberName = this.findMemberInSet(members, memberName);
-        if (!actualMemberName) {
-            return false;
-        }
-        members.delete(actualMemberName);
-        if (members.size === 0) {
-            this.channels.delete(channel);
-        }
-        // Also try case-insensitive for memberChannels cleanup
-        const memberChannelSet = this.memberChannels.get(actualMemberName) ?? this.memberChannels.get(memberName);
-        if (memberChannelSet) {
-            memberChannelSet.delete(channel);
-            if (memberChannelSet.size === 0) {
-                this.memberChannels.delete(actualMemberName);
-                this.memberChannels.delete(memberName); // Clean up both potential keys
-            }
-        }
-        if (options?.persist ?? true) {
-            this.persistChannelMembership(channel, actualMemberName, 'leave');
-        }
-        return true;
-    }
-    handleMembershipUpdate(update) {
-        if (!update.channel || !update.member) {
-            return;
-        }
-        if (update.action === 'leave') {
-            this.removeChannelMember(update.channel, update.member, { persist: false });
-        }
-        else {
-            this.addChannelMember(update.channel, update.member, { persist: false });
-        }
-    }
-}
-//# sourceMappingURL=router.js.map