@agent-relay/dashboard-server 2.0.82 → 2.0.83-beta.0

package/dist/server.js

@@ -18,6 +18,7 @@ import { listTrajectorySteps, getTrajectoryStatus, getTrajectoryHistory } from '
 import { loadTeamsConfig } from '@agent-relay/config';
 import { getMemoryMonitor } from '@agent-relay/resiliency';
 import { detectWorkspacePath, getAgentOutboxTemplate } from '@agent-relay/config';
+import { BrokerSpawnReader } from './services/broker-spawn-reader.js';
 // Dynamically find the dashboard static files directory
 // We can't import from @agent-relay/dashboard directly due to circular dependency
 function findDashboardDir() {
@@ -320,6 +321,24 @@ export async function startDashboard(portOrOptions, dataDirArg, teamDirArg, dbPa
         ? { port: portOrOptions, dataDir: dataDirArg, teamDir: teamDirArg, dbPath: dbPathArg }
         : portOrOptions;
     const { port, dataDir, teamDir, dbPath, enableSpawner, projectRoot, tmuxSession, onMarkSpawning, onClearSpawning, verbose, spawnManager: externalSpawnManager } = options;
+    let { relayAdapter } = options;
+    // Auto-create a RelayAdapter when projectRoot is available and no adapter/spawnManager is passed.
+    // This makes the dashboard self-contained — `relay-dashboard-server --integrated --project-root .`
+    // works without the CLI.
+    if (!relayAdapter && !externalSpawnManager && enableSpawner && projectRoot) {
+        try {
+            const brokerSdk = await import('@agent-relay/broker-sdk');
+            relayAdapter = new brokerSdk.RelayAdapter({
+                cwd: projectRoot,
+                clientName: 'dashboard',
+            });
+            console.log('[dashboard] Auto-created RelayAdapter for broker mode');
+        }
+        catch {
+            // @agent-relay/broker-sdk not installed — fall back to legacy AgentSpawner
+        }
+    }
+    const useBrokerAdapter = !!relayAdapter;
     // Debug logging helper - only logs when verbose is true or VERBOSE env var is set
     const isVerbose = verbose || process.env.VERBOSE === 'true';
     const debug = (message) => {
@@ -487,31 +506,41 @@ export async function startDashboard(portOrOptions, dataDirArg, teamDirArg, dbPa
     // tool directories like ~/.nvm contain package.json markers.
     const workspacePath = projectRoot || detectWorkspacePath(dataDir);
     console.log(`[dashboard] Workspace path: ${workspacePath}`);
-    // When an external SpawnManager is provided (from the daemon), use it for read operations
-    // (logs, worker listing, hasWorker) and route spawn/release through the SDK client.
-    // This solves relay-pty binary resolution issues in npx/global installs.
-    // Fall back to creating a local AgentSpawner only when no SpawnManager is provided.
+    // Spawner / SpawnReader setup — three modes:
+    // 1. Broker adapter mode: relayAdapter provides spawn/release/list via Rust binary stdio
+    // 2. External SpawnManager: daemon co-located, read ops from daemon's SpawnManager
+    // 3. Local AgentSpawner: standalone mode, spawns agents directly
     const useExternalSpawnManager = !!externalSpawnManager;
-    const spawner = enableSpawner && !useExternalSpawnManager
-        ? new AgentSpawner({
+    let brokerSpawnReader;
+    let spawner;
+    if (useBrokerAdapter) {
+        // Mode 1: Broker adapter — create BrokerSpawnReader backed by RelayAdapter
+        brokerSpawnReader = new BrokerSpawnReader(relayAdapter);
+        await relayAdapter.start();
+        await brokerSpawnReader.initialize();
+        console.log('[dashboard] Using broker adapter for spawn operations');
+    }
+    else if (!useExternalSpawnManager && enableSpawner) {
+        // Mode 3: Local AgentSpawner (legacy standalone)
+        spawner = new AgentSpawner({
             projectRoot: workspacePath,
             tmuxSession,
             dashboardPort: port,
             onMarkSpawning,
             onClearSpawning,
-        })
-        : undefined;
+        });
+    }
     // spawnReader provides read-only access to spawner state.
-    // Uses the external SpawnManager when available (daemon co-located),
-    // otherwise falls back to the local AgentSpawner.
-    const spawnReader = externalSpawnManager || spawner;
-    if (useExternalSpawnManager) {
+    // Priority: broker adapter > external SpawnManager > local AgentSpawner
+    const spawnReader = brokerSpawnReader || externalSpawnManager || spawner;
+    if (useBrokerAdapter) {
+        // Already logged above
+    }
+    else if (useExternalSpawnManager) {
         console.log('[dashboard] Using daemon SpawnManager for spawn operations (SDK-routed)');
     }
-    // Initialize cloud persistence and memory monitoring if enabled (RELAY_CLOUD_ENABLED=true)
-    // Only needed for local AgentSpawner; daemon's SpawnManager handles its own cloud persistence
-    if (spawner && !useExternalSpawnManager) {
-        // Use workspace ID from env or generate from project root
+    // Initialize cloud persistence (only for legacy local AgentSpawner mode)
+    if (spawner && !useExternalSpawnManager && !useBrokerAdapter) {
         const workspaceId = process.env.RELAY_WORKSPACE_ID ||
             crypto.createHash('sha256').update(projectRoot || dataDir).digest('hex').slice(0, 36);
         initCloudPersistence(workspaceId).then((cloudHandler) => {
@@ -522,17 +551,16 @@ export async function startDashboard(portOrOptions, dataDirArg, teamDirArg, dbPa
             console.warn('[dashboard] Failed to initialize cloud persistence:', err);
         });
     }
-    // Initialize memory monitoring for cloud deployments
-    if (spawnReader && (process.env.RELAY_CLOUD_ENABLED === 'true' || process.env.RELAY_MEMORY_MONITORING === 'true')) {
+    // Initialize memory monitoring for cloud deployments (skip in broker mode — use adapter.getMetrics())
+    if (!useBrokerAdapter && spawnReader && (process.env.RELAY_CLOUD_ENABLED === 'true' || process.env.RELAY_MEMORY_MONITORING === 'true')) {
         try {
             const memoryMonitor = getMemoryMonitor({
-                checkIntervalMs: 10000, // Check every 10 seconds
+                checkIntervalMs: 10000,
                 enableTrendAnalysis: true,
                 enableProactiveAlerts: true,
             });
             memoryMonitor.start();
             console.log('[dashboard] Memory monitoring enabled');
-            // Register existing workers with memory monitor
             const workers = spawnReader.getActiveWorkers();
             for (const worker of workers) {
                 if (worker.pid) {
@@ -882,13 +910,56 @@ export async function startDashboard(portOrOptions, dataDirArg, teamDirArg, dbPa
         });
     }
     // Relay clients for sending messages from dashboard
-    // Map of senderName -> RelayClient for per-user connections
+    // In broker adapter mode, messages go through the single RelayAdapter.
+    // In legacy mode, per-user RelayClient connections are created via socket.
     const socketPath = path.join(dataDir, 'relay.sock');
     const relayClients = new Map();
     // Forward declaration - initialized later, used by getRelayClient to avoid duplicate connections
     // eslint-disable-next-line prefer-const
     let userBridge;
+    // In broker mode, create shim objects that satisfy the RelayClient interface
+    // used by the rest of the server (sendMessage, state, spawn, release).
+    // Each shim captures a sender name for proper message attribution.
+    const brokerClientShimCache = new Map();
+    const getBrokerClientShim = (senderName) => {
+        if (!useBrokerAdapter)
+            return undefined;
+        let shim = brokerClientShimCache.get(senderName);
+        if (!shim) {
+            shim = {
+                state: 'READY',
+                sendMessage: async (to, body, _kind, _data, thread) => {
+                    await relayAdapter.sendMessage({ to, text: body, from: senderName, threadId: thread });
+                    return true;
+                },
+                spawn: async (req) => {
+                    return relayAdapter.spawn({
+                        name: req.name,
+                        cli: req.cli,
+                        task: req.task,
+                        team: req.team,
+                        cwd: req.cwd,
+                        interactive: req.interactive,
+                        shadowMode: req.shadowMode,
+                        shadowOf: req.shadowOf,
+                        spawnerName: req.spawnerName,
+                        userId: req.userId,
+                        includeWorkflowConventions: req.includeWorkflowConventions,
+                    });
+                },
+                release: async (name) => {
+                    return relayAdapter.release(name);
+                },
+            };
+            brokerClientShimCache.set(senderName, shim);
+        }
+        return shim;
+    };
     const notifyDaemonOfMembershipUpdate = async (channel, member, action, workspaceId) => {
+        if (useBrokerAdapter) {
+            // In broker mode, channel membership is managed differently — no _router message needed
+            return;
+        }
         const client = await getRelayClient('Dashboard');
         if (!client || client.state !== 'READY') {
             return;
@@ -905,14 +976,20 @@ export async function startDashboard(portOrOptions, dataDirArg, teamDirArg, dbPa
     // Track pending client connections to prevent race conditions
     const pendingConnections = new Map();
     // Get or create a relay client for a specific sender
+    // In broker adapter mode, returns a shim backed by RelayAdapter.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const getRelayClient = async (senderName = 'Dashboard', entityType) => {
+        // Broker adapter mode — return per-sender shim (always "ready")
+        if (useBrokerAdapter) {
+            return getBrokerClientShim(senderName);
+        }
+        // --- Legacy socket-based mode below ---
         // Check if we already have a connected client for this sender
         const existing = relayClients.get(senderName);
         if (existing && existing.state === 'READY') {
             return existing;
         }
         // Check if userBridge has a client for this user (avoid duplicate connections)
-        // This prevents the connection storm where two clients fight for the same name
         if (userBridge) {
             const userBridgeClient = userBridge.getRelayClient(senderName);
             if (userBridgeClient && userBridgeClient.state === 'READY') {
@@ -932,9 +1009,6 @@ export async function startDashboard(portOrOptions, dataDirArg, teamDirArg, dbPa
         }
         // Create connection promise to prevent race conditions
         const connectionPromise = (async () => {
-            // Create new client for this sender
-            // Default to 'user' entityType for non-Dashboard senders (human users)
-            // System clients (starting with '_') should NOT be users - they're internal clients
             const isSystemClient = senderName.startsWith('_') || senderName === 'Dashboard';
             const resolvedEntityType = entityType ?? (isSystemClient ? undefined : 'user');
             const client = new RelayClient({
@@ -944,7 +1018,6 @@ export async function startDashboard(portOrOptions, dataDirArg, teamDirArg, dbPa
                 cli: 'dashboard',
                 reconnect: true,
                 maxReconnectAttempts: 5,
-                // Dashboard is a reserved name, so we need to mark it as a system component
                 _isSystemComponent: senderName === 'Dashboard',
             });
             client.onError = (err) => {
@@ -952,28 +1025,17 @@ export async function startDashboard(portOrOptions, dataDirArg, teamDirArg, dbPa
             };
             client.onStateChange = (state) => {
                 console.log(`[dashboard] Relay client for ${senderName} state: ${state}`);
-                // Handle state transitions
                 if (state === 'READY') {
-                    // Re-add to map on successful reconnection
                     relayClients.set(senderName, client);
                 }
                 else if (state === 'DISCONNECTED') {
-                    // Only remove if max reconnect attempts exhausted (client gives up)
-                    // The client will auto-reconnect if configured, so don't remove prematurely
                     relayClients.delete(senderName);
                 }
             };
-            // Set up channel message handler to forward messages to presence WebSocket
-            // This enables cloud users to receive channel messages via the presence bridge
             client.onChannelMessage = (from, channel, body, envelope) => {
-                console.log(`[dashboard] *** CHANNEL MESSAGE RECEIVED *** for ${senderName}: ${from} -> ${channel}`);
-                // Look up sender's avatar from presence (if they're an online user)
                 const senderPresence = onlineUsers.get(from);
                 const fromAvatarUrl = senderPresence?.info.avatarUrl;
-                // Determine entity type: user if they have presence state, agent otherwise
                 const fromEntityType = senderPresence ? 'user' : 'agent';
-                // Broadcast to presence WebSocket clients so cloud can forward to its users
-                // Include the target user so cloud knows who to forward to
                 broadcastChannelMessage({
                     type: 'channel_message',
                     targetUser: senderName,
@@ -987,24 +1049,14 @@ export async function startDashboard(portOrOptions, dataDirArg, teamDirArg, dbPa
                     timestamp: new Date().toISOString(),
                 });
             };
-            // Set up direct message handler to forward messages to presence WebSocket
-            // This enables agents to send replies that appear in the dashboard UI
-            // Note: the relay daemon already persists messages authoritatively, so we
-            // only need to broadcast the real-time event here (no storage.saveMessage).
             client.onMessage = (from, payload, messageId) => {
                 const body = typeof payload === 'object' && payload !== null && 'body' in payload
                     ? payload.body
                     : String(payload);
-                console.log(`[dashboard] *** DIRECT MESSAGE RECEIVED *** for ${senderName}: ${from} -> ${senderName}: ${body.substring(0, 50)}...`);
-                // Look up sender's info from presence (if they're an online user)
                 const senderPresence = onlineUsers.get(from);
                 const fromAvatarUrl = senderPresence?.info.avatarUrl;
-                // Determine entity type: user if they have presence state, agent otherwise
                 const fromEntityType = senderPresence ? 'user' : 'agent';
                 const timestamp = new Date().toISOString();
-                // Broadcast real-time event so the dashboard UI updates immediately.
-                // Pass id (= messageId) so the client has a stable identifier and
-                // doesn't need to fabricate one from Date.now().
                 broadcastDirectMessage({
                     type: 'direct_message',
                     targetUser: senderName,
@@ -1028,54 +1080,96 @@ export async function startDashboard(portOrOptions, dataDirArg, teamDirArg, dbPa
                 return undefined;
             }
             finally {
-                // Clean up pending connection
                 pendingConnections.delete(senderName);
             }
         })();
-        // Store the pending connection
         pendingConnections.set(senderName, connectionPromise);
         return connectionPromise;
     };
-    // Start default relay client connection (non-blocking)
-    // Use 'Dashboard' to avoid conflicts with agents named 'Dashboard'
-    getRelayClient('Dashboard').catch(() => { });
-    // User bridge for human-to-human and human-to-agent messaging
-    userBridge = new UserBridge({
-        socketPath,
-        createRelayClient: async (options) => {
-            const client = new RelayClient({
-                socketPath: options.socketPath,
-                agentName: options.agentName,
-                entityType: options.entityType,
-                displayName: options.displayName,
-                avatarUrl: options.avatarUrl,
-                cli: 'dashboard',
-                reconnect: true,
-                maxReconnectAttempts: 5,
-            });
-            client.onError = (err) => {
-                console.error(`[user-bridge] Relay client error for ${options.agentName}:`, err.message);
-            };
-            await client.connect();
-            return client;
-        },
-        loadPersistedChannels: (username) => loadPersistedChannelsForUser(username, defaultWorkspaceId),
-        // Look up user info (avatar URL) from presence
-        lookupUserInfo: (username) => {
-            const presence = onlineUsers.get(username);
-            if (presence) {
-                return { avatarUrl: presence.info.avatarUrl };
+    // In broker mode, subscribe to relay_inbound events for message forwarding
+    if (useBrokerAdapter) {
+        relayAdapter.onEvent((event) => {
+            if (event.kind === 'relay_inbound') {
+                const senderPresence = onlineUsers.get(event.from);
+                const fromAvatarUrl = senderPresence?.info.avatarUrl;
+                const fromEntityType = senderPresence ? 'user' : 'agent';
+                const timestamp = new Date().toISOString();
+                // Route to channel or direct message based on target
+                if (event.target.startsWith('#')) {
+                    broadcastChannelMessage({
+                        type: 'channel_message',
+                        targetUser: event.target,
+                        channel: event.target,
+                        from: event.from,
+                        fromAvatarUrl,
+                        fromEntityType,
+                        body: event.body,
+                        thread: event.thread_id,
+                        timestamp,
+                    });
+                }
+                else {
+                    broadcastDirectMessage({
+                        type: 'direct_message',
+                        targetUser: event.target,
+                        from: event.from,
+                        fromAvatarUrl,
+                        fromEntityType,
+                        body: event.body,
+                        id: event.event_id,
+                        messageId: event.event_id,
+                        timestamp,
+                    });
+                }
             }
-            return undefined;
-        },
-    });
+        });
+        console.log('[dashboard] Broker event subscription active for message forwarding');
+    }
+    // Start default relay client connection (non-blocking) — skip in broker mode
+    if (!useBrokerAdapter) {
+        getRelayClient('Dashboard').catch(() => { });
+    }
+    // User bridge for human-to-human and human-to-agent messaging
+    // In broker mode, skip UserBridge — messages go through the single adapter
+    if (!useBrokerAdapter) {
+        userBridge = new UserBridge({
+            socketPath,
+            createRelayClient: async (options) => {
+                const client = new RelayClient({
+                    socketPath: options.socketPath,
+                    agentName: options.agentName,
+                    entityType: options.entityType,
+                    displayName: options.displayName,
+                    avatarUrl: options.avatarUrl,
+                    cli: 'dashboard',
+                    reconnect: true,
+                    maxReconnectAttempts: 5,
+                });
+                client.onError = (err) => {
+                    console.error(`[user-bridge] Relay client error for ${options.agentName}:`, err.message);
+                };
+                await client.connect();
+                return client;
+            },
+            loadPersistedChannels: (username) => loadPersistedChannelsForUser(username, defaultWorkspaceId),
+            lookupUserInfo: (username) => {
+                const presence = onlineUsers.get(username);
+                if (presence) {
+                    return { avatarUrl: presence.info.avatarUrl };
+                }
+                return undefined;
+            },
+        });
+    }
     // Bridge client for cross-project messaging
+    // In broker mode, cross-project messaging goes through Relaycast cloud — skip socket bridge
     let bridgeClient;
     let bridgeClientConnecting = false;
     const connectBridgeClient = async () => {
+        if (useBrokerAdapter)
+            return; // Cross-project messaging via Relaycast cloud in broker mode
         if (bridgeClient || bridgeClientConnecting)
             return;
-        // Check if bridge-state.json exists and has projects
         const bridgeStatePath = path.join(dataDir, 'bridge-state.json');
         if (!fs.existsSync(bridgeStatePath)) {
             return;
@@ -1086,28 +1180,25 @@ export async function startDashboard(portOrOptions, dataDirArg, teamDirArg, dbPa
                 return;
             }
             bridgeClientConnecting = true;
-            // Build project configs from bridge state
             const projectConfigs = bridgeState.projects.map((p) => {
-                // Compute socket path for each project
                 const projectHash = crypto.createHash('sha256').update(p.path).digest('hex').slice(0, 12);
                 const projectDataDir = path.join(path.dirname(dataDir), projectHash);
-                const socketPath = path.join(projectDataDir, 'relay.sock');
+                const projectSocketPath = path.join(projectDataDir, 'relay.sock');
                 return {
                     id: p.id,
                     path: p.path,
-                    socketPath,
+                    socketPath: projectSocketPath,
                     leadName: p.lead?.name || 'Lead',
                     cli: 'dashboard-bridge',
                 };
             });
-            // Filter to projects with existing sockets
             const validConfigs = projectConfigs.filter((p) => fs.existsSync(p.socketPath));
             if (validConfigs.length === 0) {
                 bridgeClientConnecting = false;
                 return;
             }
             bridgeClient = new MultiProjectClient(validConfigs, {
-                agentName: '__DashboardBridge__', // Unique name to avoid conflict with CLI bridge
+                agentName: '__DashboardBridge__',
                 reconnect: true,
             });
             bridgeClient.onProjectStateChange = (projectId, connected) => {
@@ -1183,7 +1274,7 @@ export async function startDashboard(portOrOptions, dataDirArg, teamDirArg, dbPa
         if (username === '*')
             return true;
         // Check local presence, userBridge registration, and remote users from cloud
-        return onlineUsers.has(username) || userBridge.isUserRegistered(username) || isRemoteUser(username);
+        return onlineUsers.has(username) || userBridge?.isUserRegistered(username) || isRemoteUser(username);
     };
     const isRecipientOnline = (name) => (isAgentOnline(name) || isRemoteAgent(name) || isUserOnline(name));
     // Helper to get team members from teams.json, agents.json, and spawner's active workers
@@ -2437,7 +2528,7 @@ export async function startDashboard(portOrOptions, dataDirArg, teamDirArg, dbPa
                 console.error(`[dashboard] Error subscribing to ${agentName}:`, err);
             });
         }
-        ws.on('message', (data) => {
+        ws.on('message', async (data) => {
             try {
                 const msg = JSON.parse(data.toString());
                 // Subscribe to agent logs
@@ -2480,7 +2571,7 @@ export async function startDashboard(portOrOptions, dataDirArg, teamDirArg, dbPa
                     }
                     // Check if this is a spawned agent (we can only send input to spawned agents)
                     if (spawnReader?.hasWorker(agentName)) {
-                        const success = spawnReader.sendWorkerInput(agentName, msg.data);
+                        const success = await spawnReader.sendWorkerInput(agentName, msg.data);
                         if (!success) {
                             console.warn(`[dashboard] Failed to send input to agent ${agentName}`);
                         }
@@ -2730,7 +2821,7 @@ export async function startDashboard(portOrOptions, dataDirArg, teamDirArg, dbPa
                             existing.info.lastSeen = now;
                             // Update userBridge to use the new WebSocket for message delivery
                             // This ensures messages are sent to an active connection, not a stale one
-                            userBridge.updateWebSocket(username, ws);
+                            userBridge?.updateWebSocket(username, ws);
                             // Only log at milestones to reduce noise
                             const count = existing.connections.size;
                             if (count === 2 || count === 5 || count === 10 || count % 50 === 0) {
@@ -2750,7 +2841,7 @@ export async function startDashboard(portOrOptions, dataDirArg, teamDirArg, dbPa
                             });
                             console.log(`[dashboard] User ${username} came online`);
                             // Register user with relay daemon for messaging
-                            userBridge.registerUser(username, ws, { avatarUrl }).catch((err) => {
+                            userBridge?.registerUser(username, ws, { avatarUrl }).catch((err) => {
                                 console.error(`[dashboard] Failed to register user ${username} with relay:`, err);
                             });
                             // Broadcast join to all other clients (only for truly new users)
@@ -2836,7 +2927,7 @@ export async function startDashboard(portOrOptions, dataDirArg, teamDirArg, dbPa
                         console.warn(`[dashboard] Invalid channel_join: missing channel`);
                         return;
                     }
-                    userBridge.joinChannel(clientUsername, msg.channel).then((success) => {
+                    userBridge?.joinChannel(clientUsername, msg.channel).then((success) => {
                         ws.send(JSON.stringify({
                             type: 'channel_joined',
                             channel: msg.channel,
@@ -2862,7 +2953,7 @@ export async function startDashboard(portOrOptions, dataDirArg, teamDirArg, dbPa
                         console.warn(`[dashboard] Invalid channel_leave: missing channel`);
                         return;
                     }
-                    userBridge.leaveChannel(clientUsername, msg.channel).then((success) => {
+                    userBridge?.leaveChannel(clientUsername, msg.channel).then((success) => {
                         ws.send(JSON.stringify({
                             type: 'channel_left',
                             channel: msg.channel,
@@ -2886,7 +2977,7 @@ export async function startDashboard(portOrOptions, dataDirArg, teamDirArg, dbPa
                         console.warn(`[dashboard] Invalid channel_message: missing body`);
                         return;
                     }
-                    userBridge.sendChannelMessage(clientUsername, msg.channel, msg.body, {
+                    userBridge?.sendChannelMessage(clientUsername, msg.channel, msg.body, {
                         thread: msg.thread,
                     }).catch((err) => {
                         console.error(`[dashboard] Channel message error:`, err);
@@ -2906,7 +2997,7 @@ export async function startDashboard(portOrOptions, dataDirArg, teamDirArg, dbPa
                         console.warn(`[dashboard] Invalid direct_message: missing body`);
                         return;
                     }
-                    userBridge.sendDirectMessage(clientUsername, msg.to, msg.body, {
+                    userBridge?.sendDirectMessage(clientUsername, msg.to, msg.body, {
                         thread: msg.thread,
                     }).catch((err) => {
                         console.error(`[dashboard] Direct message error:`, err);
@@ -2931,7 +3022,7 @@ export async function startDashboard(portOrOptions, dataDirArg, teamDirArg, dbPa
                         onlineUsers.delete(clientUsername);
                         console.log(`[dashboard] User ${clientUsername} disconnected`);
                         // Unregister from relay daemon
-                        userBridge.unregisterUser(clientUsername);
+                        userBridge?.unregisterUser(clientUsername);
                         broadcastPresence({
                             type: 'presence_leave',
                             username: clientUsername,
@@ -2964,7 +3055,7 @@ export async function startDashboard(portOrOptions, dataDirArg, teamDirArg, dbPa
             if (!username) {
                 return res.status(400).json({ error: 'username query param required' });
             }
-            const channels = userBridge.getUserChannels(username);
+            const channels = userBridge?.getUserChannels(username) ?? [];
             return res.json({
                 channels: channels.map((id) => ({
                     id,
@@ -3083,14 +3174,14 @@ export async function startDashboard(portOrOptions, dataDirArg, teamDirArg, dbPa
             // Join the creator to the channel
             // Note: userBridge.joinChannel triggers router's persistChannelMembership via protocol
             // We only persist here for dashboard-initiated creates (no daemon connection)
-            await userBridge.joinChannel(username, channelId);
+            await userBridge?.joinChannel(username, channelId);
             await persistChannelMembershipEvent(channelId, username, 'join', { workspaceId });
             // Handle invites if provided
             if (invites) {
                 const inviteList = invites.split(',').map((s) => s.trim()).filter(Boolean);
                 for (const invitee of inviteList) {
                     // userBridge.joinChannel handles persistence via protocol
-                    await userBridge.joinChannel(invitee, channelId);
+                    await userBridge?.joinChannel(invitee, channelId);
                     await persistChannelMembershipEvent(channelId, invitee, 'invite', { invitedBy: username, workspaceId });
                 }
             }
@@ -3176,8 +3267,8 @@ export async function startDashboard(portOrOptions, dataDirArg, teamDirArg, dbPa
             for (const invitee of inviteList) {
                 let success = false;
                 let reason;
-                if (userBridge.isUserRegistered(invitee.id)) {
-                    success = await userBridge.joinChannel(invitee.id, channelId);
+                if (userBridge?.isUserRegistered(invitee.id)) {
+                    success = await userBridge?.joinChannel(invitee.id, channelId);
                     if (!success) {
                         reason = 'join_failed';
                     }
@@ -3203,7 +3294,7 @@ export async function startDashboard(portOrOptions, dataDirArg, teamDirArg, dbPa
      * GET /api/channels/users - Get list of registered users
      */
     app.get('/api/channels/users', (_req, res) => {
-        const users = userBridge.getRegisteredUsers();
+        const users = userBridge?.getRegisteredUsers() ?? [];
         res.json({ users });
     });
     /**
@@ -3223,11 +3314,11 @@ export async function startDashboard(portOrOptions, dataDirArg, teamDirArg, dbPa
             : (channel.startsWith('#') ? channel : `#${channel}`);
         let success = false;
         // Step 1: Try userBridge (for users connected via local WebSocket)
-        const isLocalUser = userBridge.isUserRegistered(username);
+        const isLocalUser = userBridge?.isUserRegistered(username);
         console.log(`[channels] Join: isLocalUser=${isLocalUser}`);
         if (isLocalUser) {
             console.log(`[channels] Calling userBridge.joinChannel(${username}, ${channelId})`);
-            success = await userBridge.joinChannel(username, channelId);
+            success = await userBridge?.joinChannel(username, channelId) ?? false;
             console.log(`[channels] userBridge.joinChannel returned: ${success}`);
         }
         // Step 2: If not local or userBridge failed, use relay client fallback
@@ -3264,7 +3355,7 @@ export async function startDashboard(portOrOptions, dataDirArg, teamDirArg, dbPa
         }
         const workspaceId = resolveWorkspaceId(req);
         try {
-            const success = await userBridge.leaveChannel(username, channel);
+            const success = await userBridge?.leaveChannel(username, channel);
             if (success) {
                 await persistChannelMembershipEvent(channel, username, 'leave', { workspaceId });
             }
@@ -3286,7 +3377,7 @@ export async function startDashboard(portOrOptions, dataDirArg, teamDirArg, dbPa
         const workspaceId = resolveWorkspaceId(req);
         try {
             console.log(`[channels] Admin join: ${member} -> ${channel}`);
-            const success = await userBridge.adminJoinChannel(channel, member);
+            const success = await userBridge?.adminJoinChannel(channel, member);
             if (success) {
                 await persistChannelMembershipEvent(channel, member, 'join', { workspaceId });
             }
@@ -3329,7 +3420,7 @@ export async function startDashboard(portOrOptions, dataDirArg, teamDirArg, dbPa
         const workspaceId = resolveWorkspaceId(req);
         try {
             console.log(`[channels] Admin remove: ${member} <- ${channel}`);
-            const success = await userBridge.adminRemoveMember(channel, member);
+            const success = await userBridge?.adminRemoveMember(channel, member);
             if (success) {
                 await persistChannelMembershipEvent(channel, member, 'leave', { workspaceId });
             }
@@ -3368,7 +3459,7 @@ export async function startDashboard(portOrOptions, dataDirArg, teamDirArg, dbPa
                 }
             }
             // Get connected users from userBridge
-            const connectedUsers = userBridge.getRegisteredUsers();
+            const connectedUsers = userBridge?.getRegisteredUsers() ?? [];
             // Build member list
             const memberSet = new Set();
             // Add persisted members
@@ -3502,7 +3593,7 @@ export async function startDashboard(portOrOptions, dataDirArg, teamDirArg, dbPa
             // This prevents falling back to getRelayClient which creates a conflicting connection
             let regAttempts = 0;
             const maxRegAttempts = 20; // 2 seconds max wait
-            while (!userBridge.isUserRegistered(username) && regAttempts < maxRegAttempts) {
+            while (!userBridge?.isUserRegistered(username) && regAttempts < maxRegAttempts) {
                 await new Promise(r => setTimeout(r, 100));
                 regAttempts++;
             }
@@ -3512,13 +3603,13 @@ export async function startDashboard(portOrOptions, dataDirArg, teamDirArg, dbPa
             // Check if user is registered with userBridge (cloud users via presence)
             // This is the preferred path as it uses the existing relay connection
             // and ensures channel messages flow through the proper callback chain
-            if (userBridge.isUserRegistered(username)) {
+            if (userBridge?.isUserRegistered(username)) {
                 console.log(`[channel-debug] SUBSCRIBE via userBridge for ${username}`);
                 for (const channel of channelList) {
                     const channelId = channel.startsWith('dm:')
                         ? channel
                         : (channel.startsWith('#') ? channel : `#${channel}`);
-                    const joined = await userBridge.joinChannel(username, channelId);
+                    const joined = await userBridge?.joinChannel(username, channelId);
                     if (joined) {
                         joinedChannels.push(channelId);
                     }
@@ -3593,16 +3684,16 @@ export async function startDashboard(portOrOptions, dataDirArg, teamDirArg, dbPa
         // For cloud-proxied requests, we need to use relay client directly
         let success = false;
         // Step 1: Check if user is registered with userBridge (local mode)
-        const isLocalUser = userBridge.isUserRegistered(username);
+        const isLocalUser = userBridge?.isUserRegistered(username);
         console.log(`[channel-msg] Is local user: ${isLocalUser}`);
         if (isLocalUser) {
             // Local user - use userBridge
             console.log('[channel-msg] Using userBridge (local user)');
-            success = await userBridge.sendChannelMessage(username, channelId, body, {
+            success = await userBridge?.sendChannelMessage(username, channelId, body, {
                 thread,
                 data: workspaceId ? { _workspaceId: workspaceId } : undefined,
                 attachments,
-            });
+            }) ?? false;
             console.log(`[channel-msg] userBridge result: ${success}`);
         }
         // Step 2: If not local or userBridge failed, use relay client
@@ -3715,7 +3806,7 @@ export async function startDashboard(portOrOptions, dataDirArg, teamDirArg, dbPa
             return res.status(400).json({ error: 'from, to, and body required' });
         }
         try {
-            const success = await userBridge.sendDirectMessage(from, to, body, { thread });
+            const success = await userBridge?.sendDirectMessage(from, to, body, { thread });
             res.json({ success });
         }
         catch (err) {
@@ -4968,9 +5059,24 @@ export async function startDashboard(portOrOptions, dataDirArg, teamDirArg, dbPa
         const effectiveCwd = cwd || (spawnerName ? agentCwdMap.get(spawnerName) : undefined);
         try {
             let result;
-            if (useExternalSpawnManager) {
+            if (useBrokerAdapter) {
+                // Route spawn through broker SDK → Rust binary
+                result = await relayAdapter.spawn({
+                    name,
+                    cli,
+                    task,
+                    team: team || undefined,
+                    cwd: effectiveCwd || undefined,
+                    interactive,
+                    shadowMode,
+                    shadowOf,
+                    spawnerName: spawnerName || undefined,
+                    userId: typeof userId === 'string' ? userId : undefined,
+                    includeWorkflowConventions: true,
+                });
+            }
+            else if (useExternalSpawnManager) {
                 // Route spawn through SDK → daemon socket → SpawnManager
-                // This ensures relay-pty binary resolution works regardless of install method
                 const client = await getRelayClient('Dashboard');
                 if (!client) {
                     return res.status(503).json({
@@ -4978,8 +5084,6 @@ export async function startDashboard(portOrOptions, dataDirArg, teamDirArg, dbPa
                         error: 'Not connected to relay daemon',
                     });
                 }
-                // spawnerName/userId/includeWorkflowConventions need SDK >= 2.2.0 types
-                // Cast removed once SDK is republished with these fields
                 result = await client.spawn({
                     name,
                     cli,
@@ -5236,7 +5340,15 @@ Then output: \`->relay-file:all\`
 Start by greeting the project leads and asking for status updates.`;
         try {
             let result;
-            if (useExternalSpawnManager) {
+            if (useBrokerAdapter) {
+                result = await relayAdapter.spawn({
+                    name: 'Architect',
+                    cli,
+                    task: architectPrompt,
+                    includeWorkflowConventions: true,
+                });
+            }
+            else if (useExternalSpawnManager) {
                 const client = await getRelayClient('Dashboard');
                 if (!client) {
                     return res.status(503).json({ success: false, error: 'Not connected to relay daemon' });
@@ -5343,7 +5455,7 @@ Start by greeting the project leads and asking for status updates.`;
      * DELETE /api/spawned/:name - Release a spawned agent
      */
     app.delete('/api/spawned/:name', async (req, res) => {
-        if (!spawner && !useExternalSpawnManager) {
+        if (!spawner && !useExternalSpawnManager && !useBrokerAdapter) {
             return res.status(503).json({
                 success: false,
                 error: 'Spawner not enabled',
@@ -5352,8 +5464,11 @@ Start by greeting the project leads and asking for status updates.`;
         const { name } = req.params;
         try {
             let released;
-            if (useExternalSpawnManager) {
-                // Route release through SDK → daemon socket → SpawnManager
+            if (useBrokerAdapter) {
+                const result = await relayAdapter.release(name);
+                released = result.success;
+            }
+            else if (useExternalSpawnManager) {
                 const client = await getRelayClient('Dashboard');
                 if (!client) {
                     return res.status(503).json({ success: false, error: 'Not connected to relay daemon' });
@@ -5396,7 +5511,7 @@ Start by greeting the project leads and asking for status updates.`;
      * Sends ESC ESC (0x1b 0x1b) to the agent's PTY to interrupt the current operation.
      * This is useful for breaking agents out of stuck loops without terminating them.
      */
-    app.post('/api/agents/by-name/:name/interrupt', (req, res) => {
+    app.post('/api/agents/by-name/:name/interrupt', async (req, res) => {
         if (!spawnReader) {
             return res.status(503).json({
                 success: false,
@@ -5414,7 +5529,7 @@ Start by greeting the project leads and asking for status updates.`;
         try {
             // Send ESC ESC sequence to interrupt the agent
             // ESC = 0x1b in hexadecimal
-            const success = spawnReader.sendWorkerInput(name, '\x1b\x1b');
+            const success = await spawnReader.sendWorkerInput(name, '\x1b\x1b');
             if (success) {
                 console.log(`[api] Sent interrupt (ESC ESC) to agent ${name}`);
                 res.json({