nterminal 1.2.76 → 1.2.78

package/dist/server/routes/agentManagementRoutes.js

@@ -8,6 +8,7 @@ import { requireAllowedOrigin } from './authRoutes.js';
 import { authenticateTerminalRequest } from './terminalRoutes.js';
 import { proxyAgentRequest } from '../agent/agentProxy.js';
 import { proxyAgentWebSocket } from '../agent/agentWebSocketProxy.js';
+import { OutboundAgentRegistry } from '../agent/outboundAgentRegistry.js';
 import { collectSystemStats } from '../system/stats.js';
 import { createManualUpdateInfo, isPermissionUpdateFailure } from '../../shared/manualUpdate.js';
 import { MAIN_SERVER_ID } from '../../shared/protocol.js';
@@ -28,6 +29,7 @@ const hopByHopHeaders = new Set([
     'upgrade'
 ]);
 export async function registerAgentManagementRoutes(app, config, services) {
+    const outboundAgentRegistry = services.outboundAgentRegistry ?? new OutboundAgentRegistry();
     // List agents
     app.get('/api/agents', async (request, reply) => {
         const auth = await authenticateTerminalRequest(services.authService, request, reply);
@@ -35,7 +37,13 @@ export async function registerAgentManagementRoutes(app, config, services) {
             return reply;
         const state = await services.fileStore.read();
         return {
-            agents: state.agents.map(({ id, name, url }) => ({ id, name, url })),
+            agents: state.agents.map(({ id, name, url, transport }) => ({
+                id,
+                name,
+                url,
+                ...(transport === 'outbound' ? { transport } : {}),
+                ...(transport === 'outbound' ? { connected: outboundAgentRegistry.status(id).connected } : {})
+            })),
             serverOrder: state.serverOrder
         };
     });
@@ -69,22 +77,29 @@ export async function registerAgentManagementRoutes(app, config, services) {
         if (!auth)
             return reply;
         const { name, url, token } = request.body ?? {};
+        const transport = request.body?.transport === 'outbound' ? 'outbound' : 'direct';
         if (typeof name !== 'string' || !name.trim())
             return reply.code(400).send({ error: 'name_required' });
-        if (typeof url !== 'string' || !url.trim())
+        if (request.body?.transport !== undefined && request.body.transport !== 'direct' && request.body.transport !== 'outbound') {
+            return reply.code(400).send({ error: 'invalid_transport' });
+        }
+        if (transport === 'direct' && (typeof url !== 'string' || !url.trim()))
             return reply.code(400).send({ error: 'url_required' });
         if (typeof token !== 'string' || token.length < 32)
             return reply.code(400).send({ error: 'token_too_short' });
-        const normalizedUrl = normalizeAgentUrl(url);
+        const normalizedUrl = transport === 'direct' ? normalizeAgentUrl(url) : { ok: true, url: null };
         if (!normalizedUrl.ok) {
             return reply.code(400).send({ error: normalizedUrl.error });
         }
         const agentName = name.trim();
         let agent = null;
         let created = false;
+        const removedAgentIds = [];
         await services.fileStore.update((state) => {
             const tokenMatchIndex = state.agents.findIndex((a) => a.token === token);
-            const urlMatchIndex = state.agents.findIndex((a) => a.url === normalizedUrl.url);
+            const urlMatchIndex = normalizedUrl.url
+                ? state.agents.findIndex((a) => a.transport === 'direct' && a.url === normalizedUrl.url)
+                : -1;
             const existingIndex = tokenMatchIndex >= 0 ? tokenMatchIndex : urlMatchIndex;
             if (existingIndex === -1) {
                 created = true;
@@ -92,6 +107,7 @@ export async function registerAgentManagementRoutes(app, config, services) {
                     id: randomUUID(),
                     name: agentName,
                     url: normalizedUrl.url,
+                    transport,
                     token,
                     createdAt: new Date().toISOString()
                 };
@@ -103,14 +119,14 @@ export async function registerAgentManagementRoutes(app, config, services) {
                 ...existing,
                 name: agentName,
                 url: normalizedUrl.url,
+                transport,
                 token
             };
-            const removedAgentIds = [];
             const agents = state.agents.flatMap((current, index) => {
                 if (index === existingIndex) {
                     return [agent];
                 }
-                if (current.url === normalizedUrl.url || current.token === token) {
+                if ((normalizedUrl.url !== null && current.transport === 'direct' && current.url === normalizedUrl.url) || current.token === token) {
                     removedAgentIds.push(current.id);
                     return [];
                 }
@@ -142,7 +158,19 @@ export async function registerAgentManagementRoutes(app, config, services) {
             }
             return { ...state, agents, serverOrder, agentLayouts, agentManualUpdates };
         }, { flush: 'immediate' });
-        return reply.code(created ? 201 : 200).send({ agent: { id: agent.id, name: agent.name, url: agent.url } });
+        for (const removedAgentId of removedAgentIds)
+            outboundAgentRegistry.disconnect(removedAgentId);
+        if (agent.transport === 'direct')
+            outboundAgentRegistry.disconnect(agent.id);
+        return reply.code(created ? 201 : 200).send({
+            agent: {
+                id: agent.id,
+                name: agent.name,
+                url: agent.url,
+                ...(agent.transport === 'outbound' ? { transport: agent.transport } : {}),
+                ...(agent.transport === 'outbound' ? { connected: outboundAgentRegistry.status(agent.id).connected } : {})
+            }
+        });
     });
     app.put('/api/agents/order', { preHandler: (request, reply) => requireAllowedOrigin(config, request, reply) }, async (request, reply) => {
         const auth = await authenticateTerminalRequest(services.authService, request, reply);
@@ -183,7 +211,13 @@ export async function registerAgentManagementRoutes(app, config, services) {
                     return nextAgentIds.shift();
                 });
             }
-            reorderedAgents = agents.map(({ id, name, url }) => ({ id, name, url }));
+            reorderedAgents = agents.map(({ id, name, url, transport }) => ({
+                id,
+                name,
+                url,
+                ...(transport === 'outbound' ? { transport } : {}),
+                ...(transport === 'outbound' ? { connected: outboundAgentRegistry.status(id).connected } : {})
+            }));
             return { ...state, agents, serverOrder };
         }, { flush: 'immediate' });
         if (!validOrder || !reorderedAgents || !serverOrder) {
@@ -222,6 +256,7 @@ export async function registerAgentManagementRoutes(app, config, services) {
         const found = await removeAgentRegistration(services.fileStore, request.params.agentId);
         if (!found)
             return reply.code(404).send({ error: 'agent_not_found' });
+        outboundAgentRegistry.disconnect(request.params.agentId);
         return reply.code(204).send();
     });
     app.post('/api/agents/:agentId/uninstall', { preHandler: (request, reply) => requireAllowedOrigin(config, request, reply) }, async (request, reply) => {
@@ -230,13 +265,14 @@ export async function registerAgentManagementRoutes(app, config, services) {
             return reply;
         if (config.previewMode)
             return reply.code(403).send({ error: 'preview_mode' });
-        const agent = await resolveAgent(services.fileStore, request.params.agentId);
+        const agent = await resolveAgent(services.fileStore, outboundAgentRegistry, request.params.agentId, reply);
         if (!agent)
-            return reply.code(404).send({ error: 'agent_not_found' });
+            return reply;
         const uninstall = await requestAgentUninstall(agent);
         const found = await removeAgentRegistration(services.fileStore, request.params.agentId);
         if (!found)
             return reply.code(404).send({ error: 'agent_not_found' });
+        outboundAgentRegistry.disconnect(request.params.agentId);
         return {
             ok: true,
             message: uninstall.message,
@@ -258,9 +294,9 @@ export async function registerAgentManagementRoutes(app, config, services) {
         const auth = await authenticateTerminalRequest(services.authService, request, reply);
         if (!auth)
             return reply;
-        const agent = await resolveAgent(services.fileStore, request.params.agentId);
+        const agent = await resolveAgent(services.fileStore, outboundAgentRegistry, request.params.agentId, reply);
         if (!agent)
-            return reply.code(404).send({ error: 'agent_not_found' });
+            return reply;
         return proxyAgentRequest(agent, '/stats', request, reply, {
             timeoutMs: 2500,
             transformJson: (json, status) => {
@@ -278,10 +314,9 @@ export async function registerAgentManagementRoutes(app, config, services) {
         const auth = await authenticateTerminalRequest(services.authService, request, reply);
         if (!auth)
             return reply;
-        const state = await services.fileStore.read();
-        const agent = state.agents.find((a) => a.id === request.params.agentId);
+        const agent = await resolveAgent(services.fileStore, outboundAgentRegistry, request.params.agentId, reply);
         if (!agent)
-            return reply.code(404).send({ error: 'agent_not_found' });
+            return reply;
         const start = Date.now();
         try {
             const res = await fetch(`${agent.url}/api/agent/terminals`, {
@@ -301,9 +336,9 @@ export async function registerAgentManagementRoutes(app, config, services) {
         const auth = await authenticateTerminalRequest(services.authService, request, reply);
         if (!auth)
             return reply;
-        const agent = await resolveAgent(services.fileStore, request.params.agentId);
+        const agent = await resolveAgent(services.fileStore, outboundAgentRegistry, request.params.agentId, reply);
         if (!agent)
-            return reply.code(404).send({ error: 'agent_not_found' });
+            return reply;
         return proxyAgentRequest(agent, '/version', request, reply, {
             transformJson: async (json) => {
                 if (!isVersionInfoBody(json)) {
@@ -322,9 +357,9 @@ export async function registerAgentManagementRoutes(app, config, services) {
         const auth = await authenticateTerminalRequest(services.authService, request, reply);
         if (!auth)
             return reply;
-        const agent = await resolveAgent(services.fileStore, request.params.agentId);
+        const agent = await resolveAgent(services.fileStore, outboundAgentRegistry, request.params.agentId, reply);
         if (!agent)
-            return reply.code(404).send({ error: 'agent_not_found' });
+            return reply;
         return proxyAgentRequest(agent, '/update/check', request, reply, {
             transformJson: async (json) => {
                 if (isUpdateCheckBody(json) && !json.error && json.updateAvailable === false) {
@@ -341,9 +376,9 @@ export async function registerAgentManagementRoutes(app, config, services) {
         if (config.previewMode) {
             return { ok: false, changed: false, message: 'Agent updates are disabled in preview mode.', restarting: false };
         }
-        const agent = await resolveAgent(services.fileStore, request.params.agentId);
+        const agent = await resolveAgent(services.fileStore, outboundAgentRegistry, request.params.agentId, reply);
         if (!agent)
-            return reply.code(404).send({ error: 'agent_not_found' });
+            return reply;
         return proxyAgentRequest(agent, '/update', request, reply, {
             transformJson: async (json) => {
                 if (!isUpdateResponseBody(json)) {
@@ -372,9 +407,9 @@ export async function registerAgentManagementRoutes(app, config, services) {
         const auth = await authenticateTerminalRequest(services.authService, request, reply);
         if (!auth)
             return reply;
-        const agent = await resolveAgent(services.fileStore, request.params.agentId);
+        const agent = await resolveAgent(services.fileStore, outboundAgentRegistry, request.params.agentId, reply);
         if (!agent)
-            return reply.code(404).send({ error: 'agent_not_found' });
+            return reply;
         const query = request.url.includes('?') ? request.url.slice(request.url.indexOf('?')) : '';
         return proxyAgentRequest(agent, `/code-server/status${query}`, request, reply, {
             transformJson: (json) => rewriteCodeServerResponseForAgent(request.params.agentId, json)
@@ -389,9 +424,9 @@ export async function registerAgentManagementRoutes(app, config, services) {
         // on the production agent, so preview blocks them all.
         if (config.previewMode)
             return reply.code(403).send({ error: 'preview_mode' });
-        const agent = await resolveAgent(services.fileStore, request.params.agentId);
+        const agent = await resolveAgent(services.fileStore, outboundAgentRegistry, request.params.agentId, reply);
         if (!agent)
-            return reply.code(404).send({ error: 'agent_not_found' });
+            return reply;
         return proxyAgentRequest(agent, '/code-server/install', request, reply, {
             transformJson: (json) => rewriteCodeServerResponseForAgent(request.params.agentId, json)
         });
@@ -402,9 +437,9 @@ export async function registerAgentManagementRoutes(app, config, services) {
             return reply;
         if (config.previewMode)
             return reply.code(403).send({ error: 'preview_mode' });
-        const agent = await resolveAgent(services.fileStore, request.params.agentId);
+        const agent = await resolveAgent(services.fileStore, outboundAgentRegistry, request.params.agentId, reply);
         if (!agent)
-            return reply.code(404).send({ error: 'agent_not_found' });
+            return reply;
         return proxyAgentRequest(agent, '/code-server/update', request, reply, {
             transformJson: (json) => rewriteCodeServerResponseForAgent(request.params.agentId, json)
         });
@@ -415,9 +450,9 @@ export async function registerAgentManagementRoutes(app, config, services) {
             return reply;
         if (config.previewMode)
             return reply.code(403).send({ error: 'preview_mode' });
-        const agent = await resolveAgent(services.fileStore, request.params.agentId);
+        const agent = await resolveAgent(services.fileStore, outboundAgentRegistry, request.params.agentId, reply);
         if (!agent)
-            return reply.code(404).send({ error: 'agent_not_found' });
+            return reply;
         return proxyAgentRequest(agent, '/code-server/open', request, reply, {
             bodyOverride: {
                 ...(request.body ?? {}),
@@ -432,9 +467,9 @@ export async function registerAgentManagementRoutes(app, config, services) {
             return reply;
         if (config.previewMode)
             return reply.code(403).send({ error: 'preview_mode' });
-        const agent = await resolveAgent(services.fileStore, request.params.agentId);
+        const agent = await resolveAgent(services.fileStore, outboundAgentRegistry, request.params.agentId, reply);
         if (!agent)
-            return reply.code(404).send({ error: 'agent_not_found' });
+            return reply;
         return proxyAgentRequest(agent, '/code-server/stop', request, reply, {
             transformJson: (json) => rewriteCodeServerResponseForAgent(request.params.agentId, json)
         });
@@ -445,9 +480,9 @@ export async function registerAgentManagementRoutes(app, config, services) {
             return reply;
         if (config.previewMode)
             return reply.code(403).send({ error: 'preview_mode' });
-        const agent = await resolveAgent(services.fileStore, request.params.agentId);
+        const agent = await resolveAgent(services.fileStore, outboundAgentRegistry, request.params.agentId, reply);
         if (!agent)
-            return reply.code(404).send({ error: 'agent_not_found' });
+            return reply;
         return proxyAgentRequest(agent, '/code-server/uninstall', request, reply, {
             transformJson: (json) => rewriteCodeServerResponseForAgent(request.params.agentId, json)
         });
@@ -457,18 +492,18 @@ export async function registerAgentManagementRoutes(app, config, services) {
         const auth = await authenticateTerminalRequest(services.authService, request, reply);
         if (!auth)
             return reply;
-        const agent = await resolveAgent(services.fileStore, request.params.agentId);
+        const agent = await resolveAgent(services.fileStore, outboundAgentRegistry, request.params.agentId, reply);
         if (!agent)
-            return reply.code(404).send({ error: 'agent_not_found' });
+            return reply;
         return proxyAgentRequest(agent, '/terminals', request, reply);
     });
     app.get('/api/agents/:agentId/terminals/:terminalId/history', async (request, reply) => {
         const auth = await authenticateTerminalRequest(services.authService, request, reply);
         if (!auth)
             return reply;
-        const agent = await resolveAgent(services.fileStore, request.params.agentId);
+        const agent = await resolveAgent(services.fileStore, outboundAgentRegistry, request.params.agentId, reply);
         if (!agent)
-            return reply.code(404).send({ error: 'agent_not_found' });
+            return reply;
         const query = request.url.includes('?') ? request.url.slice(request.url.indexOf('?')) : '';
         return proxyAgentRequest(agent, `/terminals/${request.params.terminalId}/history${query}`, request, reply);
     });
@@ -476,9 +511,9 @@ export async function registerAgentManagementRoutes(app, config, services) {
         const auth = await authenticateTerminalRequest(services.authService, request, reply);
         if (!auth)
             return reply;
-        const agent = await resolveAgent(services.fileStore, request.params.agentId);
+        const agent = await resolveAgent(services.fileStore, outboundAgentRegistry, request.params.agentId, reply);
         if (!agent)
-            return reply.code(404).send({ error: 'agent_not_found' });
+            return reply;
         const query = request.url.includes('?') ? request.url.slice(request.url.indexOf('?')) : '';
         return proxyAgentRequest(agent, `/terminals/${request.params.terminalId}/transcript-history${query}`, request, reply, {
             unavailableFallback: {
@@ -494,9 +529,9 @@ export async function registerAgentManagementRoutes(app, config, services) {
         const auth = await authenticateTerminalRequest(services.authService, request, reply);
         if (!auth)
             return reply;
-        const agent = await resolveAgent(services.fileStore, request.params.agentId);
+        const agent = await resolveAgent(services.fileStore, outboundAgentRegistry, request.params.agentId, reply);
         if (!agent)
-            return reply.code(404).send({ error: 'agent_not_found' });
+            return reply;
         return proxyAgentRequest(agent, `/terminals/${request.params.terminalId}/transcript-source`, request, reply, {
             unavailableFallback: { terminalId: request.params.terminalId, source: null }
         });
@@ -506,9 +541,9 @@ export async function registerAgentManagementRoutes(app, config, services) {
         const auth = await authenticateTerminalRequest(services.authService, request, reply);
         if (!auth)
             return reply;
-        const agent = await resolveAgent(services.fileStore, request.params.agentId);
+        const agent = await resolveAgent(services.fileStore, outboundAgentRegistry, request.params.agentId, reply);
         if (!agent)
-            return reply.code(404).send({ error: 'agent_not_found' });
+            return reply;
         return proxyAgentRequest(agent, '/terminals', request, reply);
     });
     // Proxy: close terminal
@@ -516,9 +551,9 @@ export async function registerAgentManagementRoutes(app, config, services) {
         const auth = await authenticateTerminalRequest(services.authService, request, reply);
         if (!auth)
             return reply;
-        const agent = await resolveAgent(services.fileStore, request.params.agentId);
+        const agent = await resolveAgent(services.fileStore, outboundAgentRegistry, request.params.agentId, reply);
         if (!agent)
-            return reply.code(404).send({ error: 'agent_not_found' });
+            return reply;
         return proxyAgentRequest(agent, `/terminals/${request.params.terminalId}`, request, reply);
     });
     // Proxy: rename terminal
@@ -526,9 +561,9 @@ export async function registerAgentManagementRoutes(app, config, services) {
         const auth = await authenticateTerminalRequest(services.authService, request, reply);
         if (!auth)
             return reply;
-        const agent = await resolveAgent(services.fileStore, request.params.agentId);
+        const agent = await resolveAgent(services.fileStore, outboundAgentRegistry, request.params.agentId, reply);
         if (!agent)
-            return reply.code(404).send({ error: 'agent_not_found' });
+            return reply;
         return proxyAgentRequest(agent, `/terminals/${request.params.terminalId}`, request, reply);
     });
     // Proxy: terminal WebSocket
@@ -542,13 +577,12 @@ export async function registerAgentManagementRoutes(app, config, services) {
             socket.close(1008, 'unauthorized');
             return;
         }
-        const state = await services.fileStore.read();
-        const agent = state.agents.find((a) => a.id === request.params.agentId);
-        if (!agent) {
-            socket.close(1008, 'agent not found');
+        const resolution = await resolveAgentConnection(services.fileStore, outboundAgentRegistry, request.params.agentId);
+        if (resolution.status !== 'resolved') {
+            closeAgentWebSocket(socket, resolution.status);
             return;
         }
-        proxyAgentWebSocket(socket, agent, request.params.terminalId);
+        proxyAgentWebSocket(socket, resolution.agent, request.params.terminalId);
     });
     // Proxy: file routes (all file operations)
     const filePathParts = ['root', 'list', 'read', 'write', 'create', 'move', 'delete-preview', 'delete', 'open', 'preview'];
@@ -557,9 +591,9 @@ export async function registerAgentManagementRoutes(app, config, services) {
             const auth = await authenticateTerminalRequest(services.authService, request, reply);
             if (!auth)
                 return reply;
-            const agent = await resolveAgent(services.fileStore, request.params.agentId);
+            const agent = await resolveAgent(services.fileStore, outboundAgentRegistry, request.params.agentId, reply);
             if (!agent)
-                return reply.code(404).send({ error: 'agent_not_found' });
+                return reply;
             return proxyAgentRequest(agent, `/files/${part}`, request, reply);
         });
     }
@@ -567,14 +601,13 @@ export async function registerAgentManagementRoutes(app, config, services) {
         const auth = await authenticateTerminalRequest(services.authService, request, reply);
         if (!auth)
             return reply;
-        if (!await resolveAgent(services.fileStore, request.params.agentId)) {
-            return reply.code(404).send({ error: 'agent_not_found' });
-        }
+        if (!await resolveAgent(services.fileStore, outboundAgentRegistry, request.params.agentId, reply))
+            return reply;
         return reply.redirect(`${agentCodeServerPublicPrefix(request.params.agentId, request.params.instanceId)}/`, 302);
     });
-    await registerAgentCodeServerProxyRoutes(app, config, services);
+    await registerAgentCodeServerProxyRoutes(app, config, services, outboundAgentRegistry);
 }
-async function registerAgentCodeServerProxyRoutes(app, config, services) {
+async function registerAgentCodeServerProxyRoutes(app, config, services, outboundAgentRegistry) {
     await app.register(async (proxyApp) => {
         registerStreamingBodyParser(proxyApp);
         proxyApp.route({
@@ -587,9 +620,9 @@ async function registerAgentCodeServerProxyRoutes(app, config, services) {
                     return reply;
                 if (!isProxyOriginAcceptable(config, request))
                     return reply.code(403).send({ error: 'origin_not_allowed' });
-                const agent = await resolveAgent(services.fileStore, request.params.agentId);
+                const agent = await resolveAgent(services.fileStore, outboundAgentRegistry, request.params.agentId, reply);
                 if (!agent)
-                    return reply.code(404).send({ error: 'agent_not_found' });
+                    return reply;
                 proxyAgentCodeServerHttp(agent, request, reply);
                 return reply;
             },
@@ -603,12 +636,12 @@ async function registerAgentCodeServerProxyRoutes(app, config, services) {
                     socket.close(1008, 'unauthorized');
                     return;
                 }
-                const agent = await resolveAgent(services.fileStore, request.params.agentId);
-                if (!agent) {
-                    socket.close(1008, 'agent not found');
+                const resolution = await resolveAgentConnection(services.fileStore, outboundAgentRegistry, request.params.agentId);
+                if (resolution.status !== 'resolved') {
+                    closeAgentWebSocket(socket, resolution.status);
                     return;
                 }
-                proxyAgentCodeServerWebSocket(agent, socket, request);
+                proxyAgentCodeServerWebSocket(resolution.agent, socket, request);
             }
         });
         for (const method of httpProxyMethods) {
@@ -622,9 +655,9 @@ async function registerAgentCodeServerProxyRoutes(app, config, services) {
                         return reply;
                     if (!isProxyOriginAcceptable(config, request))
                         return reply.code(403).send({ error: 'origin_not_allowed' });
-                    const agent = await resolveAgent(services.fileStore, request.params.agentId);
+                    const agent = await resolveAgent(services.fileStore, outboundAgentRegistry, request.params.agentId, reply);
                     if (!agent)
-                        return reply.code(404).send({ error: 'agent_not_found' });
+                        return reply;
                     proxyAgentCodeServerHttp(agent, request, reply);
                     return reply;
                 }
@@ -774,12 +807,10 @@ function rewriteAgentCodeServerLocation(value, agent, agentId, instanceId) {
     }
     try {
         const parsed = new URL(value);
-        const agentOrigin = new URL(agent.url).origin;
-        if (parsed.origin === agentOrigin) {
-            const rewritten = rewriteAgentCodeServerLocation(`${parsed.pathname}${parsed.search}${parsed.hash}`, agent, agentId, instanceId);
-            if (rewritten !== `${parsed.pathname}${parsed.search}${parsed.hash}`) {
-                return rewritten;
-            }
+        const pathAndSuffix = `${parsed.pathname}${parsed.search}${parsed.hash}`;
+        const rewritten = rewriteAgentCodeServerLocation(pathAndSuffix, agent, agentId, instanceId);
+        if (rewritten !== pathAndSuffix) {
+            return rewritten;
         }
     }
     catch {
@@ -863,9 +894,32 @@ function websocketProtocols(value) {
 function isRecord(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
-async function resolveAgent(fileStore, agentId) {
+async function resolveAgent(fileStore, outboundAgentRegistry, agentId, reply) {
+    const resolution = await resolveAgentConnection(fileStore, outboundAgentRegistry, agentId);
+    if (resolution.status === 'resolved')
+        return resolution.agent;
+    if (resolution.status === 'not_found') {
+        reply?.code(404).send({ error: 'agent_not_found' });
+    }
+    else {
+        reply?.code(502).send({ error: 'agent_unreachable' });
+    }
+    return null;
+}
+async function resolveAgentConnection(fileStore, outboundAgentRegistry, agentId) {
     const state = await fileStore.read();
-    return state.agents.find((a) => a.id === agentId) ?? null;
+    const agent = state.agents.find((candidate) => candidate.id === agentId);
+    if (!agent)
+        return { status: 'not_found' };
+    const resolved = outboundAgentRegistry.resolve(agent);
+    return resolved ? { status: 'resolved', agent: resolved } : { status: 'unreachable' };
+}
+function closeAgentWebSocket(socket, status) {
+    if (status === 'not_found') {
+        socket.close(1008, 'agent not found');
+        return;
+    }
+    socket.close(1013, 'agent temporarily unavailable');
 }
 function pickPreferredAgentLayout(current, candidate) {
     if (!current)