agent-relay 1.2.3 → 1.3.1

package/dist/dashboard-server/user-bridge.d.ts

@@ -0,0 +1,103 @@
+/**
+ * User Bridge - Bridges dashboard WebSocket users to the relay daemon.
+ *
+ * This module allows human users connected via WebSocket to:
+ * - Register as "user" entities in the relay daemon
+ * - Join/leave channels
+ * - Send/receive messages through the relay daemon
+ * - Communicate with agents and other users
+ */
+import type { WebSocket } from 'ws';
+/**
+ * Relay client interface (subset of RelayClient for dependency injection)
+ */
+export interface IRelayClient {
+    connect(): Promise<void>;
+    disconnect(): void;
+    state: string;
+    sendMessage(to: string, body: string, kind?: string, data?: unknown, thread?: string): boolean;
+    onMessage?: (from: string, payload: any, messageId: string, meta?: any, originalTo?: string) => void;
+}
+/**
+ * Factory function type for creating relay clients
+ */
+export type RelayClientFactory = (options: {
+    socketPath: string;
+    agentName: string;
+    entityType: 'user';
+    displayName?: string;
+    avatarUrl?: string;
+}) => Promise<IRelayClient>;
+/**
+ * Options for creating a UserBridge
+ */
+export interface UserBridgeOptions {
+    socketPath: string;
+    createRelayClient: RelayClientFactory;
+}
+/**
+ * Message options for sending
+ */
+export interface SendMessageOptions {
+    thread?: string;
+    data?: Record<string, unknown>;
+}
+/**
+ * UserBridge manages the connection between dashboard WebSocket users
+ * and the relay daemon.
+ */
+export declare class UserBridge {
+    private readonly socketPath;
+    private readonly createRelayClient;
+    private readonly users;
+    constructor(options: UserBridgeOptions);
+    /**
+     * Register a user with the relay daemon.
+     * Creates a relay client connection for the user.
+     */
+    registerUser(username: string, webSocket: WebSocket, options?: {
+        avatarUrl?: string;
+        displayName?: string;
+    }): Promise<void>;
+    /**
+     * Unregister a user and disconnect their relay client.
+     */
+    unregisterUser(username: string): void;
+    /**
+     * Check if a user is registered.
+     */
+    isUserRegistered(username: string): boolean;
+    /**
+     * Get list of all registered users.
+     */
+    getRegisteredUsers(): string[];
+    /**
+     * Join a channel.
+     */
+    joinChannel(username: string, channel: string): Promise<boolean>;
+    /**
+     * Leave a channel.
+     */
+    leaveChannel(username: string, channel: string): Promise<boolean>;
+    /**
+     * Get channels a user has joined.
+     */
+    getUserChannels(username: string): string[];
+    /**
+     * Send a message to a channel.
+     */
+    sendChannelMessage(username: string, channel: string, body: string, options?: SendMessageOptions): Promise<boolean>;
+    /**
+     * Send a direct message to another user or agent.
+     */
+    sendDirectMessage(fromUsername: string, toName: string, body: string, options?: SendMessageOptions): Promise<boolean>;
+    /**
+     * Handle incoming message from relay daemon.
+     */
+    private handleIncomingMessage;
+    /**
+     * Dispose of all user sessions.
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=user-bridge.d.ts.map

package/dist/dashboard-server/user-bridge.js

@@ -0,0 +1,189 @@
+/**
+ * User Bridge - Bridges dashboard WebSocket users to the relay daemon.
+ *
+ * This module allows human users connected via WebSocket to:
+ * - Register as "user" entities in the relay daemon
+ * - Join/leave channels
+ * - Send/receive messages through the relay daemon
+ * - Communicate with agents and other users
+ */
+/**
+ * UserBridge manages the connection between dashboard WebSocket users
+ * and the relay daemon.
+ */
+export class UserBridge {
+    socketPath;
+    createRelayClient;
+    users = new Map();
+    constructor(options) {
+        this.socketPath = options.socketPath;
+        this.createRelayClient = options.createRelayClient;
+    }
+    /**
+     * Register a user with the relay daemon.
+     * Creates a relay client connection for the user.
+     */
+    async registerUser(username, webSocket, options) {
+        // If user already registered, unregister first
+        if (this.users.has(username)) {
+            this.unregisterUser(username);
+        }
+        // Create relay client for this user
+        const relayClient = await this.createRelayClient({
+            socketPath: this.socketPath,
+            agentName: username,
+            entityType: 'user',
+            displayName: options?.displayName,
+            avatarUrl: options?.avatarUrl,
+        });
+        // Connect to daemon
+        await relayClient.connect();
+        // Set up message handler to forward messages to WebSocket
+        relayClient.onMessage = (from, payload, _messageId, _meta, _originalTo) => {
+            const body = typeof payload === 'object' && payload !== null && 'body' in payload
+                ? payload.body
+                : String(payload);
+            this.handleIncomingMessage(username, from, body, payload);
+        };
+        // Create session
+        const session = {
+            username,
+            relayClient,
+            webSocket,
+            channels: new Set(),
+            avatarUrl: options?.avatarUrl,
+        };
+        this.users.set(username, session);
+        // Set up WebSocket close handler
+        webSocket.on('close', () => {
+            this.unregisterUser(username);
+        });
+        console.log(`[user-bridge] User ${username} registered with relay daemon`);
+    }
+    /**
+     * Unregister a user and disconnect their relay client.
+     */
+    unregisterUser(username) {
+        const session = this.users.get(username);
+        if (!session)
+            return;
+        session.relayClient.disconnect();
+        this.users.delete(username);
+        console.log(`[user-bridge] User ${username} unregistered from relay daemon`);
+    }
+    /**
+     * Check if a user is registered.
+     */
+    isUserRegistered(username) {
+        return this.users.has(username);
+    }
+    /**
+     * Get list of all registered users.
+     */
+    getRegisteredUsers() {
+        return Array.from(this.users.keys());
+    }
+    /**
+     * Join a channel.
+     */
+    async joinChannel(username, channel) {
+        const session = this.users.get(username);
+        if (!session) {
+            console.warn(`[user-bridge] Cannot join channel - user ${username} not registered`);
+            return false;
+        }
+        // Send channel join via relay client
+        session.relayClient.sendMessage(channel, '', 'channel_join');
+        // Track membership
+        session.channels.add(channel);
+        console.log(`[user-bridge] User ${username} joined channel ${channel}`);
+        return true;
+    }
+    /**
+     * Leave a channel.
+     */
+    async leaveChannel(username, channel) {
+        const session = this.users.get(username);
+        if (!session) {
+            console.warn(`[user-bridge] Cannot leave channel - user ${username} not registered`);
+            return false;
+        }
+        // Send channel leave via relay client
+        session.relayClient.sendMessage(channel, '', 'channel_leave');
+        // Update membership
+        session.channels.delete(channel);
+        console.log(`[user-bridge] User ${username} left channel ${channel}`);
+        return true;
+    }
+    /**
+     * Get channels a user has joined.
+     */
+    getUserChannels(username) {
+        const session = this.users.get(username);
+        return session ? Array.from(session.channels) : [];
+    }
+    /**
+     * Send a message to a channel.
+     */
+    async sendChannelMessage(username, channel, body, options) {
+        const session = this.users.get(username);
+        if (!session) {
+            console.warn(`[user-bridge] Cannot send - user ${username} not registered`);
+            return false;
+        }
+        return session.relayClient.sendMessage(channel, body, 'message', options?.data, options?.thread);
+    }
+    /**
+     * Send a direct message to another user or agent.
+     */
+    async sendDirectMessage(fromUsername, toName, body, options) {
+        const session = this.users.get(fromUsername);
+        if (!session) {
+            console.warn(`[user-bridge] Cannot send DM - user ${fromUsername} not registered`);
+            return false;
+        }
+        return session.relayClient.sendMessage(toName, body, 'message', options?.data, options?.thread);
+    }
+    /**
+     * Handle incoming message from relay daemon.
+     */
+    handleIncomingMessage(username, from, body, envelope) {
+        const session = this.users.get(username);
+        if (!session)
+            return;
+        const ws = session.webSocket;
+        if (ws.readyState !== 1)
+            return; // Not OPEN
+        // Determine message type from envelope
+        const env = envelope;
+        if (env.type === 'CHANNEL_MESSAGE') {
+            // Channel message
+            ws.send(JSON.stringify({
+                type: 'channel_message',
+                channel: env.payload?.channel,
+                from,
+                body: env.payload?.body || body,
+                timestamp: new Date().toISOString(),
+            }));
+        }
+        else {
+            // Direct message (DELIVER)
+            ws.send(JSON.stringify({
+                type: 'direct_message',
+                from,
+                body: env.payload?.body || body,
+                timestamp: new Date().toISOString(),
+            }));
+        }
+    }
+    /**
+     * Dispose of all user sessions.
+     */
+    dispose() {
+        for (const [username] of this.users) {
+            this.unregisterUser(username);
+        }
+        console.log('[user-bridge] Disposed all user sessions');
+    }
+}
+//# sourceMappingURL=user-bridge.js.map

package/dist/protocol/channels.d.ts

@@ -0,0 +1,205 @@
+/**
+ * Channel and User Protocol Types
+ *
+ * Extends the Agent Relay Protocol to support:
+ * - First-class user entities (humans, not just AI agents)
+ * - Channels for group communication
+ * - Direct messaging between any combination of users and agents
+ */
+import { PROTOCOL_VERSION, type Envelope } from './types.js';
+export { PROTOCOL_VERSION };
+/**
+ * Entity types in the relay system.
+ * - 'agent': AI agent (Claude, GPT, etc.)
+ * - 'user': Human user (via dashboard)
+ */
+export type EntityType = 'agent' | 'user';
+/**
+ * Extended message types for channels.
+ */
+export type ChannelMessageType = 'CHANNEL_JOIN' | 'CHANNEL_LEAVE' | 'CHANNEL_MESSAGE' | 'CHANNEL_INFO' | 'CHANNEL_MEMBERS' | 'CHANNEL_TYPING';
+/**
+ * Check if an entity type represents a user.
+ */
+export declare function isUserEntity(entityType: EntityType | undefined): boolean;
+/**
+ * Check if an entity type represents an agent.
+ * Undefined defaults to agent for backwards compatibility.
+ */
+export declare function isAgentEntity(entityType: EntityType | undefined): boolean;
+/**
+ * Attachment metadata for messages.
+ */
+export interface MessageAttachment {
+    id: string;
+    filename: string;
+    mimeType: string;
+    size: number;
+    url?: string;
+    data?: string;
+}
+/**
+ * Payload for CHANNEL_JOIN message.
+ * Sent when a user or agent joins a channel.
+ */
+export interface ChannelJoinPayload {
+    /** The channel to join (e.g., '#general', 'dm:alice:bob') */
+    channel: string;
+    /** Optional display name for the channel member list */
+    displayName?: string;
+    /** Optional avatar URL */
+    avatarUrl?: string;
+}
+/**
+ * Payload for CHANNEL_LEAVE message.
+ * Sent when a user or agent leaves a channel.
+ */
+export interface ChannelLeavePayload {
+    /** The channel to leave */
+    channel: string;
+    /** Optional reason for leaving */
+    reason?: string;
+}
+/**
+ * Payload for CHANNEL_MESSAGE.
+ * Sent when posting a message to a channel.
+ */
+export interface ChannelMessagePayload {
+    /** The target channel */
+    channel: string;
+    /** Message content */
+    body: string;
+    /** Optional thread ID for threaded replies */
+    thread?: string;
+    /** Optional attachments */
+    attachments?: MessageAttachment[];
+    /** Optional metadata */
+    data?: Record<string, unknown>;
+    /** Optional list of mentioned users/agents */
+    mentions?: string[];
+}
+/**
+ * Channel member info.
+ */
+export interface ChannelMember {
+    name: string;
+    entityType: EntityType;
+    displayName?: string;
+    avatarUrl?: string;
+    status?: 'online' | 'away' | 'offline';
+}
+/**
+ * Payload for CHANNEL_INFO.
+ * Contains metadata about a channel.
+ */
+export interface ChannelInfoPayload {
+    /** Channel identifier */
+    channel: string;
+    /** Human-readable channel name */
+    name: string;
+    /** Optional description */
+    description?: string;
+    /** Optional current topic */
+    topic?: string;
+    /** List of members */
+    members: ChannelMember[];
+    /** When the channel was created */
+    createdAt: string;
+    /** Whether the channel is private */
+    isPrivate?: boolean;
+}
+/**
+ * Payload for CHANNEL_MEMBERS.
+ * List of members in a channel.
+ */
+export interface ChannelMembersPayload {
+    channel: string;
+    members: ChannelMember[];
+}
+/**
+ * Payload for CHANNEL_TYPING.
+ * Indicates someone is typing in a channel.
+ */
+export interface ChannelTypingPayload {
+    channel: string;
+    isTyping: boolean;
+}
+export type ChannelJoinEnvelope = Envelope<ChannelJoinPayload> & {
+    type: 'CHANNEL_JOIN';
+};
+export type ChannelLeaveEnvelope = Envelope<ChannelLeavePayload> & {
+    type: 'CHANNEL_LEAVE';
+};
+export type ChannelMessageEnvelope = Envelope<ChannelMessagePayload> & {
+    type: 'CHANNEL_MESSAGE';
+};
+export type ChannelInfoEnvelope = Envelope<ChannelInfoPayload> & {
+    type: 'CHANNEL_INFO';
+};
+/**
+ * Type guard to check if an envelope is a channel message.
+ */
+export declare function isChannelMessage(envelope: {
+    type: string;
+}): envelope is ChannelMessageEnvelope;
+/**
+ * Type guard to check if an envelope is a channel join.
+ */
+export declare function isChannelJoin(envelope: {
+    type: string;
+}): envelope is ChannelJoinEnvelope;
+/**
+ * Type guard to check if an envelope is a channel leave.
+ */
+export declare function isChannelLeave(envelope: {
+    type: string;
+}): envelope is ChannelLeaveEnvelope;
+/**
+ * Create a CHANNEL_JOIN envelope.
+ */
+export declare function createChannelJoinEnvelope(from: string, channel: string, options?: {
+    displayName?: string;
+    avatarUrl?: string;
+}): ChannelJoinEnvelope;
+/**
+ * Create a CHANNEL_LEAVE envelope.
+ */
+export declare function createChannelLeaveEnvelope(from: string, channel: string, reason?: string): ChannelLeaveEnvelope;
+/**
+ * Create a CHANNEL_MESSAGE envelope.
+ */
+export declare function createChannelMessageEnvelope(from: string, channel: string, body: string, options?: {
+    thread?: string;
+    mentions?: string[];
+    attachments?: MessageAttachment[];
+    data?: Record<string, unknown>;
+}): ChannelMessageEnvelope;
+/**
+ * Parse a DM channel name to extract participants.
+ * DM channels follow the format: dm:<participant1>:<participant2>:...
+ */
+export declare function parseDmChannel(channel: string): string[] | null;
+/**
+ * Create a DM channel name from participants.
+ * Participants are sorted alphabetically for consistency.
+ */
+export declare function createDmChannelName(...participants: string[]): string;
+/**
+ * Check if a channel is a DM (direct message).
+ */
+export declare function isDmChannel(channel: string): boolean;
+/**
+ * Check if a channel is private.
+ */
+export declare function isPrivateChannel(channel: string): boolean;
+/**
+ * Check if a channel is a public channel (starts with #).
+ */
+export declare function isPublicChannel(channel: string): boolean;
+/**
+ * Normalize channel name for storage/lookup.
+ * - Removes leading # from public channels
+ * - Sorts participants in DM channels
+ */
+export declare function normalizeChannelName(channel: string): string;
+//# sourceMappingURL=channels.d.ts.map

package/dist/protocol/channels.js

@@ -0,0 +1,154 @@
+/**
+ * Channel and User Protocol Types
+ *
+ * Extends the Agent Relay Protocol to support:
+ * - First-class user entities (humans, not just AI agents)
+ * - Channels for group communication
+ * - Direct messaging between any combination of users and agents
+ */
+import { v4 as uuid } from 'uuid';
+import { PROTOCOL_VERSION } from './types.js';
+// Re-export PROTOCOL_VERSION for convenience
+export { PROTOCOL_VERSION };
+/**
+ * Check if an entity type represents a user.
+ */
+export function isUserEntity(entityType) {
+    return entityType === 'user';
+}
+/**
+ * Check if an entity type represents an agent.
+ * Undefined defaults to agent for backwards compatibility.
+ */
+export function isAgentEntity(entityType) {
+    return entityType === 'agent' || entityType === undefined;
+}
+/**
+ * Type guard to check if an envelope is a channel message.
+ */
+export function isChannelMessage(envelope) {
+    return envelope.type === 'CHANNEL_MESSAGE';
+}
+/**
+ * Type guard to check if an envelope is a channel join.
+ */
+export function isChannelJoin(envelope) {
+    return envelope.type === 'CHANNEL_JOIN';
+}
+/**
+ * Type guard to check if an envelope is a channel leave.
+ */
+export function isChannelLeave(envelope) {
+    return envelope.type === 'CHANNEL_LEAVE';
+}
+/**
+ * Create a CHANNEL_JOIN envelope.
+ */
+export function createChannelJoinEnvelope(from, channel, options) {
+    return {
+        v: PROTOCOL_VERSION,
+        type: 'CHANNEL_JOIN',
+        id: uuid(),
+        ts: Date.now(),
+        from,
+        payload: {
+            channel,
+            displayName: options?.displayName,
+            avatarUrl: options?.avatarUrl,
+        },
+    };
+}
+/**
+ * Create a CHANNEL_LEAVE envelope.
+ */
+export function createChannelLeaveEnvelope(from, channel, reason) {
+    return {
+        v: PROTOCOL_VERSION,
+        type: 'CHANNEL_LEAVE',
+        id: uuid(),
+        ts: Date.now(),
+        from,
+        payload: {
+            channel,
+            reason,
+        },
+    };
+}
+/**
+ * Create a CHANNEL_MESSAGE envelope.
+ */
+export function createChannelMessageEnvelope(from, channel, body, options) {
+    return {
+        v: PROTOCOL_VERSION,
+        type: 'CHANNEL_MESSAGE',
+        id: uuid(),
+        ts: Date.now(),
+        from,
+        payload: {
+            channel,
+            body,
+            thread: options?.thread,
+            mentions: options?.mentions,
+            attachments: options?.attachments,
+            data: options?.data,
+        },
+    };
+}
+/**
+ * Parse a DM channel name to extract participants.
+ * DM channels follow the format: dm:<participant1>:<participant2>:...
+ */
+export function parseDmChannel(channel) {
+    if (!channel.startsWith('dm:')) {
+        return null;
+    }
+    const parts = channel.split(':').slice(1);
+    return parts.length >= 2 ? parts : null;
+}
+/**
+ * Create a DM channel name from participants.
+ * Participants are sorted alphabetically for consistency.
+ */
+export function createDmChannelName(...participants) {
+    if (participants.length < 2) {
+        throw new Error('DM requires at least 2 participants');
+    }
+    const sorted = [...participants].sort();
+    return `dm:${sorted.join(':')}`;
+}
+/**
+ * Check if a channel is a DM (direct message).
+ */
+export function isDmChannel(channel) {
+    return channel.startsWith('dm:');
+}
+/**
+ * Check if a channel is private.
+ */
+export function isPrivateChannel(channel) {
+    return channel.startsWith('private:');
+}
+/**
+ * Check if a channel is a public channel (starts with #).
+ */
+export function isPublicChannel(channel) {
+    return channel.startsWith('#');
+}
+/**
+ * Normalize channel name for storage/lookup.
+ * - Removes leading # from public channels
+ * - Sorts participants in DM channels
+ */
+export function normalizeChannelName(channel) {
+    if (channel.startsWith('#')) {
+        return channel.slice(1);
+    }
+    if (channel.startsWith('dm:')) {
+        const participants = parseDmChannel(channel);
+        if (participants) {
+            return createDmChannelName(...participants);
+        }
+    }
+    return channel;
+}
+//# sourceMappingURL=channels.js.map

package/dist/protocol/types.d.ts

@@ -3,7 +3,7 @@
  * Version 1.0
  */
 export declare const PROTOCOL_VERSION = 1;
-export type MessageType = 'HELLO' | 'WELCOME' | 'SEND' | 'DELIVER' | 'ACK' | 'NACK' | 'PING' | 'PONG' | 'ERROR' | 'BUSY' | 'RESUME' | 'BYE' | 'STATE' | 'SYNC' | 'SYNC_SNAPSHOT' | 'SYNC_DELTA' | 'SUBSCRIBE' | 'UNSUBSCRIBE' | 'SHADOW_BIND' | 'SHADOW_UNBIND' | 'LOG';
+export type MessageType = 'HELLO' | 'WELCOME' | 'SEND' | 'DELIVER' | 'ACK' | 'NACK' | 'PING' | 'PONG' | 'ERROR' | 'BUSY' | 'RESUME' | 'BYE' | 'STATE' | 'SYNC' | 'SYNC_SNAPSHOT' | 'SYNC_DELTA' | 'SUBSCRIBE' | 'UNSUBSCRIBE' | 'SHADOW_BIND' | 'SHADOW_UNBIND' | 'LOG' | 'CHANNEL_JOIN' | 'CHANNEL_LEAVE' | 'CHANNEL_MESSAGE' | 'CHANNEL_INFO' | 'CHANNEL_MEMBERS' | 'CHANNEL_TYPING';
 export type PayloadKind = 'message' | 'action' | 'state' | 'thinking';
 export interface Envelope<T = unknown> {
     v: number;
@@ -15,6 +15,12 @@ export interface Envelope<T = unknown> {
     topic?: string;
     payload: T;
 }
+/**
+ * Entity type distinguishes between AI agents and human users.
+ * - 'agent': AI agent (Claude, GPT, custom agents)
+ * - 'user': Human user (via dashboard WebSocket)
+ */
+export type EntityType = 'agent' | 'user';
 export interface HelloPayload {
     agent: string;
     capabilities: {
@@ -23,6 +29,8 @@ export interface HelloPayload {
         max_inflight: number;
         supports_topics: boolean;
     };
+    /** Entity type: 'agent' (default) or 'user' for human users */
+    entityType?: EntityType;
     /** Optional hint about which CLI the agent is using (claude, codex, gemini, etc.) */
     cli?: string;
     /** Optional program identifier (e.g., 'claude', 'gpt-4o') */
@@ -33,6 +41,10 @@ export interface HelloPayload {
     task?: string;
     /** Optional working directory hint for registry/dashboard */
     workingDirectory?: string;
+    /** Display name for human users */
+    displayName?: string;
+    /** Avatar URL for human users */
+    avatarUrl?: string;
     session?: {
         resume_token?: string;
     };

package/dist/resiliency/provider-context.js

@@ -197,6 +197,8 @@ export class CodexContextHandler extends ProviderContextHandler {
         config.history = config.history || {};
         config.history.save_history = true;
         config.history.max_history_size = 1000;
+        // Disable Codex auto-update checks to keep container-stable version
+        config.check_for_updates = false;
         // Point to our system prompt if using custom context
         if (this.codexConfig.systemPromptPath) {
             config.system_prompt_file = this.codexConfig.systemPromptPath;