Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
Route Vite through the collaboration host (#3053)
Dimitri POSTOLOVe87fef724681
diff --git a/.changeset/centralize-collaboration-host.md b/.changeset/centralize-collaboration-host.mdnew file mode 100644index 000000000..7af636fd1--- /dev/null+++ b/.changeset/centralize-collaboration-host.md@@ -0,0 +1,6 @@+---+"@inkeep/open-knowledge": patch+"@inkeep/open-knowledge-server": patch+---++Route the Vite development server through the same collaboration WebSocket host as `ok start`, so `/collab`, `/collab/keepalive`, and `/collab/thread` share admission, message-size, presence-cleanup, and shutdown behavior. This removes the duplicated upgrade stack that could drift between development and production.diff --git a/packages/app/src/server/hocuspocus-plugin.test.ts b/packages/app/src/server/hocuspocus-plugin.test.tsindex 5c4cbcf7b..dd90f39f2 100644--- a/packages/app/src/server/hocuspocus-plugin.test.ts+++ b/packages/app/src/server/hocuspocus-plugin.test.ts@@ -97,10 +97,43 @@ describe('hocuspocusPlugin.configureServer middleware ordering', () => {innerAssetCalls += 1;};const createAssetServeMiddlewareSpy = vi.fn(() => innerAssetFn);+ const handleUpgrade = vi.fn(() => false);+ const teardownOrder: string[] = [];+ let resolveHostShutdown: (() => void) | undefined;+ const hostShutdown = new Promise<void>((resolve) => {+ resolveHostShutdown = resolve;+ });+ const fakeHost = {+ handleUpgrade,+ shutdown: vi.fn(async () => {+ teardownOrder.push('host');+ await hostShutdown;+ }),+ wss: {+ close: (done: (err?: Error) => void) => {+ teardownOrder.push('wss');+ done();+ },+ },+ };+ const createCollaborationHostSpy = vi.fn(() => fakeHost);+ const acpInit = vi.fn(async () => {});+ const acpDestroy = vi.fn(async () => {+ teardownOrder.push('acp');+ });+ class FakeAcpThreadManager {+ init = acpInit;+ destroy = acpDestroy;+ }+ const destroyServer = vi.fn(async () => {+ teardownOrder.push('server');+ });vi.doMock('@inkeep/open-knowledge-server', () => ({...actualServerPkg,+ AcpThreadManager: FakeAcpThreadManager,createAssetServeMiddleware: createAssetServeMiddlewareSpy,+ createCollaborationHost: createCollaborationHostSpy,createServer: () => ({lockDir: testContentDir,contentFilter: { isPathIgnored: () => false },@@ -115,7 +148,8 @@ describe('hocuspocusPlugin.configureServer middleware ordering', () => {sessionManager: { closeAllForAgent: async () => {} },agentFocusBroadcaster: { clearFocus: () => {} },agentPresenceBroadcaster: { clearPresence: () => {}, bumpPresenceTs: () => {} },- destroy: async () => {},+ maintenanceCoordinator: {},+ destroy: destroyServer,}),handleCollabSocketError: () => false,parseKeepaliveConnectionId: () => null,@@ -160,6 +194,14 @@ describe('hocuspocusPlugin.configureServer middleware ordering', () => {// Asset middleware factory was called exactly once.expect(createAssetServeMiddlewareSpy).toHaveBeenCalledTimes(1);+ expect(createCollaborationHostSpy).toHaveBeenCalledTimes(1);+ expect(createCollaborationHostSpy).toHaveBeenCalledWith(+ expect.objectContaining({+ maintenanceCoordinator: expect.anything(),+ hocuspocus: expect.anything(),+ }),+ );+ expect(httpServer.listeners('upgrade')).toEqual([handleUpgrade]);// Two middlewares were registered synchronously: the asset wrapper +// the api handler.@@ -204,5 +246,281 @@ describe('hocuspocusPlugin.configureServer middleware ordering', () => {assetWrapper({ url: nonBypassUrl }, {}, () => {});}expect(innerAssetCalls).toBe(4);++ let buildEndSettled = false;+ const buildEnd = Promise.resolve(plugin.buildEnd?.call(plugin)).then(() => {+ buildEndSettled = true;+ });+ await new Promise((resolve) => setTimeout(resolve, 0));+ expect(fakeHost.shutdown).toHaveBeenCalledOnce();+ expect(buildEndSettled).toBe(false);+ httpServer.emit('close');+ expect(fakeHost.shutdown).toHaveBeenCalledOnce();+ expect(teardownOrder).toEqual(['acp', 'host']);+ resolveHostShutdown?.();+ await buildEnd;+ expect(buildEndSettled).toBe(true);+ expect(fakeHost.shutdown).toHaveBeenCalledOnce();+ expect(acpDestroy).toHaveBeenCalledOnce();+ expect(destroyServer).toHaveBeenCalledOnce();+ expect(teardownOrder).toEqual(['acp', 'host', 'wss', 'server']);+ expect(httpServer.listeners('upgrade')).toEqual([]);+ });++ test('buildEnd awaits every overlapping configureServer runtime', async () => {+ const testContentDir = mkTmp();+ process.env.OK_TEST_CONTENT_DIR = testContentDir;+ const shutdowns = [Promise.withResolvers<void>(), Promise.withResolvers<void>()];+ const destroyServers = [vi.fn(async () => {}), vi.fn(async () => {})];+ const hosts = shutdowns.map((shutdown) => ({+ handleUpgrade: vi.fn(() => false),+ shutdown: vi.fn(() => shutdown.promise),+ wss: { close: (done: (err?: Error) => void) => done() },+ }));+ let serverIndex = 0;+ let hostIndex = 0;+ class FakeAcpThreadManager {+ async init(): Promise<void> {}+ async destroy(): Promise<void> {}+ }+ vi.doMock('@inkeep/open-knowledge-server', () => ({+ ...actualServerPkg,+ AcpThreadManager: FakeAcpThreadManager,+ createAssetServeMiddleware: () => () => {},+ createCollaborationHost: () => {+ const host = hosts[hostIndex++];+ if (host === undefined) throw new Error('missing fake host');+ return host;+ },+ createServer: () => {+ const destroy = destroyServers[serverIndex++];+ if (destroy === undefined) throw new Error('missing fake server');+ return {+ lockDir: testContentDir,+ contentFilter: { isPathIgnored: () => false, isExcluded: () => false },+ hocuspocus: { hooks: async () => {} },+ sessionManager: {},+ agentFocusBroadcaster: {},+ agentPresenceBroadcaster: {},+ maintenanceCoordinator: {},+ destroy,+ };+ },+ getLogger: () => ({ info: () => {}, error: () => {} }),+ makeLazyEmbeddingsKeyStore: () => ({}),+ releaseServerLock: () => {},+ updateServerLockPort: () => {},+ }));+ const { hocuspocusPlugin } = await import('./hocuspocus-plugin.ts?overlap-test');+ const makeViteServer = () => {+ const httpServer = new EventEmitter() as EventEmitter & {+ address: () => null;+ };+ httpServer.address = () => null;+ const middlewares = { use: () => middlewares };+ return { httpServer, middlewares };+ };+ const plugin = hocuspocusPlugin();+ const first = makeViteServer();+ const second = makeViteServer();+ // biome-ignore lint/suspicious/noExplicitAny: EventEmitter Vite stub+ await (plugin.configureServer as any).call(plugin, first);+ // biome-ignore lint/suspicious/noExplicitAny: EventEmitter Vite stub+ await (plugin.configureServer as any).call(plugin, second);++ let buildEndSettled = false;+ const buildEnd = Promise.resolve(plugin.buildEnd?.call(plugin)).then(() => {+ buildEndSettled = true;+ });+ await new Promise((resolve) => setImmediate(resolve));+ for (const host of hosts) expect(host.shutdown).toHaveBeenCalledOnce();+ expect(buildEndSettled).toBe(false);+ shutdowns[0]?.resolve();+ await new Promise((resolve) => setImmediate(resolve));+ expect(buildEndSettled).toBe(false);+ shutdowns[1]?.resolve();+ await buildEnd;+ expect(buildEndSettled).toBe(true);+ for (const destroy of destroyServers) expect(destroy).toHaveBeenCalledOnce();+ });++ test('bounds WebSocket close and force-terminates clients before continuing teardown', async () => {+ vi.useFakeTimers();+ try {+ const testContentDir = mkTmp();+ process.env.OK_TEST_CONTENT_DIR = testContentDir;+ const order: string[] = [];+ const logger = { info: vi.fn(), error: vi.fn() };+ const terminateClient = vi.fn(() => {+ order.push('client');+ });+ class FakeAcpThreadManager {+ async init(): Promise<void> {}+ async destroy(): Promise<void> {+ order.push('acp');+ }+ }+ const host = {+ handleUpgrade: vi.fn(() => false),+ shutdown: vi.fn(async () => {+ order.push('host');+ }),+ wss: {+ clients: new Set([{ terminate: terminateClient }]),+ close: vi.fn((_done: (err?: Error) => void) => {+ order.push('wss');+ }),+ },+ };+ const destroy = vi.fn(async () => {+ order.push('server');+ });+ vi.doMock('@inkeep/open-knowledge-server', () => ({+ ...actualServerPkg,+ AcpThreadManager: FakeAcpThreadManager,+ createAssetServeMiddleware: () => () => {},+ createCollaborationHost: () => host,+ createServer: () => ({+ lockDir: testContentDir,+ contentFilter: { isPathIgnored: () => false, isExcluded: () => false },+ hocuspocus: { hooks: async () => {} },+ sessionManager: {},+ agentFocusBroadcaster: {},+ agentPresenceBroadcaster: {},+ maintenanceCoordinator: {},+ destroy,+ }),+ getLogger: () => logger,+ makeLazyEmbeddingsKeyStore: () => ({}),+ releaseServerLock: () => {},+ updateServerLockPort: () => {},+ }));+ const { hocuspocusPlugin } = await import('./hocuspocus-plugin.ts?wss-timeout-test');+ const httpServer = new EventEmitter() as EventEmitter & { address: () => null };+ httpServer.address = () => null;+ const middlewares = { use: () => middlewares };+ const plugin = hocuspocusPlugin();+ // biome-ignore lint/suspicious/noExplicitAny: EventEmitter Vite stub+ await (plugin.configureServer as any).call(plugin, { httpServer, middlewares });++ let buildEndSettled = false;+ const buildEndResult = Promise.resolve(plugin.buildEnd?.call(plugin)).then(+ () => {+ buildEndSettled = true;+ return undefined;+ },+ (err: unknown) => {+ buildEndSettled = true;+ return err;+ },+ );+ await vi.advanceTimersByTimeAsync(0);+ expect(order).toEqual(['acp', 'host', 'wss']);+ expect(buildEndSettled).toBe(false);++ await vi.advanceTimersByTimeAsync(4_999);+ expect(terminateClient).not.toHaveBeenCalled();+ expect(buildEndSettled).toBe(false);++ await vi.advanceTimersByTimeAsync(1);+ const buildEndError = await buildEndResult;+ expect(buildEndError).toBeInstanceOf(AggregateError);+ expect(terminateClient).toHaveBeenCalledOnce();+ expect(host.wss.close).toHaveBeenCalledOnce();+ expect(destroy).toHaveBeenCalledOnce();+ expect(order).toEqual(['acp', 'host', 'wss', 'client', 'server']);+ expect(logger.error).toHaveBeenCalledWith(+ expect.objectContaining({ err: expect.any(Error) }),+ 'Vite collaboration teardown failed: WebSocket server',+ );+ } finally {+ vi.useRealTimers();+ }+ });++ test('propagates buildEnd AggregateError and contains HTTP-close fallback failures', async () => {+ const testContentDir = mkTmp();+ process.env.OK_TEST_CONTENT_DIR = testContentDir;+ const order: string[] = [];+ const logger = { info: vi.fn(), error: vi.fn() };+ class FakeAcpThreadManager {+ async init(): Promise<void> {}+ async destroy(): Promise<void> {+ order.push('acp');+ throw new Error('acp failed');+ }+ }+ const host = {+ handleUpgrade: vi.fn(() => false),+ shutdown: vi.fn(async () => {+ order.push('host');+ throw new Error('host failed');+ }),+ wss: {+ close: (done: (err?: Error) => void) => {+ order.push('wss');+ done(new Error('wss failed'));+ },+ },+ };+ const destroy = vi.fn(async () => {+ order.push('server');+ throw new Error('server failed');+ });+ vi.doMock('@inkeep/open-knowledge-server', () => ({+ ...actualServerPkg,+ AcpThreadManager: FakeAcpThreadManager,+ createAssetServeMiddleware: () => () => {},+ createCollaborationHost: () => host,+ createServer: () => ({+ lockDir: testContentDir,+ contentFilter: { isPathIgnored: () => false, isExcluded: () => false },+ hocuspocus: { hooks: async () => {} },+ sessionManager: {},+ agentFocusBroadcaster: {},+ agentPresenceBroadcaster: {},+ maintenanceCoordinator: {},+ destroy,+ }),+ getLogger: () => logger,+ makeLazyEmbeddingsKeyStore: () => ({}),+ releaseServerLock: () => {},+ updateServerLockPort: () => {},+ }));+ const { hocuspocusPlugin } = await import('./hocuspocus-plugin.ts?fallback-test');+ const httpServer = new EventEmitter() as EventEmitter & { address: () => null };+ httpServer.address = () => null;+ const middlewares = { use: () => middlewares };+ const plugin = hocuspocusPlugin();+ // biome-ignore lint/suspicious/noExplicitAny: EventEmitter Vite stub+ await (plugin.configureServer as any).call(plugin, { httpServer, middlewares });++ const buildEndError: unknown = await Promise.resolve(plugin.buildEnd?.call(plugin)).then(+ () => undefined,+ (err: unknown) => err,+ );++ expect(buildEndError).toBeInstanceOf(AggregateError);+ if (!(buildEndError instanceof AggregateError)) {+ throw new Error('buildEnd did not propagate an AggregateError');+ }+ expect(buildEndError.message).toBe('Hocuspocus Vite teardown failed');+ expect(buildEndError.errors).toHaveLength(1);+ const runtimeError = buildEndError.errors[0];+ expect(runtimeError).toBeInstanceOf(AggregateError);+ if (!(runtimeError instanceof AggregateError)) {+ throw new Error('runtime teardown did not aggregate phase failures');+ }+ expect(runtimeError.message).toBe('Vite collaboration teardown failed');+ expect(runtimeError.errors).toHaveLength(4);+ expect(order).toEqual(['acp', 'host', 'wss', 'server']);++ httpServer.emit('close');+ await new Promise((resolve) => setTimeout(resolve, 0));+ expect(logger.error).toHaveBeenCalledWith(+ expect.objectContaining({ err: expect.any(AggregateError) }),+ 'HTTP close fallback teardown failed',+ );+ await expect(plugin.buildEnd?.call(plugin)).resolves.toBeUndefined();});});diff --git a/packages/app/src/server/hocuspocus-plugin.ts b/packages/app/src/server/hocuspocus-plugin.tsindex 99a08896c..0327ca7c5 100644--- a/packages/app/src/server/hocuspocus-plugin.ts+++ b/packages/app/src/server/hocuspocus-plugin.ts@@ -23,21 +23,18 @@ import {} from '@inkeep/open-knowledge-core';import {AcpThreadManager,- attachAcpThreadSocket,buildOkMcpStdioCommand,createAssetServeMiddleware,+ createCollaborationHost,createServer,getLogger,- handleCollabSocketError,makeLazyEmbeddingsKeyStore,- parseKeepaliveConnectionId,releaseServerLock,- toBroadcasterKey,updateServerLockPort,} from '@inkeep/open-knowledge-server';import sirv from 'sirv';import type { Plugin } from 'vite';-import { WebSocketServer } from 'ws';+import type { WebSocketServer } from 'ws';import { parse as parseYaml } from 'yaml';import { computeDevApiConfigResponse } from './api-config-handler.ts';@@ -101,9 +98,6 @@ const TEST_PROJECT_DIR = process.env.OK_TEST_PROJECT_DIR? realpathSync(process.env.OK_TEST_PROJECT_DIR): undefined;-const KEEPALIVE_GRACE_MS = 10_000;-const MAX_COLLAB_MESSAGE_BYTES = 1024 * 1024;-// Gate the process.once('exit', ...) registration to avoid tripping// MaxListenersExceededWarning after ~10 Vite restarts. The exit handler// reads `latestLockDir` inside its closure so a Vite restart that swaps@@ -112,17 +106,66 @@ const MAX_COLLAB_MESSAGE_BYTES = 1024 * 1024;let exitHandlerRegistered = false;let latestLockDir: string | null = null;+const VITE_WSS_CLOSE_TIMEOUT_MS = 5_000;++function closeWebSocketServer(wss: WebSocketServer): Promise<void> {+ return new Promise<void>((resolve, reject) => {+ let settled = false;+ const timer = setTimeout(() => {+ if (settled) return;+ settled = true;+ const terminationErrors: unknown[] = [];+ for (const client of wss.clients) {+ try {+ client.terminate();+ } catch (err) {+ terminationErrors.push(err);+ }+ }+ const timeoutError = new Error(+ `WebSocket server close timed out after ${VITE_WSS_CLOSE_TIMEOUT_MS}ms`,+ );+ reject(+ terminationErrors.length === 0+ ? timeoutError+ : new AggregateError(+ [timeoutError, ...terminationErrors],+ 'WebSocket server close timed out and client termination failed',+ ),+ );+ }, VITE_WSS_CLOSE_TIMEOUT_MS);+ timer.unref?.();++ const settle = (err?: unknown): void => {+ if (settled) return;+ settled = true;+ clearTimeout(timer);+ if (err) reject(err);+ else resolve();+ };++ try {+ wss.close(settle);+ } catch (err) {+ settle(err);+ }+ });+}+export function hocuspocusPlugin(): Plugin {+ const activeRuntimeTeardowns = new Set<() => Promise<void>>();return {name: 'hocuspocus',+ async buildEnd() {+ const results = await Promise.allSettled(+ [...activeRuntimeTeardowns].map((teardown) => teardown()),+ );+ const errors = results+ .filter((result): result is PromiseRejectedResult => result.status === 'rejected')+ .map((result) => result.reason);+ if (errors.length > 0) throw new AggregateError(errors, 'Hocuspocus Vite teardown failed');+ },async configureServer(server) {- // Per-invocation closure state. On Vite restart the OLD close handler- // sets its own `shuttingDown = true` on its own binding; the NEW- // invocation starts fresh. Mirrors boot.ts's closure shape.- const keepaliveGraceTimers = new Map<string, ReturnType<typeof setTimeout>>();- const keepaliveGraceInflight = new Set<Promise<void>>();- let shuttingDown = false;-configureServerInvocations += 1;if (configureServerInvocations > 1) {console.warn(@@ -223,229 +266,16 @@ export function hocuspocusPlugin(): Plugin {// Rehydrate archived threads before the first `list` can arrive.await acpThreadManager?.init();- const wss = new WebSocketServer({ noServer: true, maxPayload: MAX_COLLAB_MESSAGE_BYTES });- wss.on('error', (err) => {- console.error('[collab] WebSocketServer error:', err);- });-- // `prependListener` intercepts /collab BEFORE Vite's HMR handler.- //- // Instrumented because `/collab` has reported-but-non-reproducible- // failure modes where the HTTP Upgrade never completes (Chrome shows- // Status: pending, 0 B). The four log lines below pinpoint where in- // the chain a stuck connection halted:- //- // [collab] upgrade received … — event reached our listener- // [collab] handleUpgrade starting — path matched, pre-ws handoff- // [collab] handleUpgrade threw … — sync throw (e.g. double-upgrade)- // [collab] handshake complete … — 101 sent; hocuspocus takes over- //- // If a stuck WS report shows none of these lines for the offending- // connection, the upgrade never reached this listener.- server.httpServer?.prependListener('upgrade', (req, socket, head) => {- if (!req.url?.startsWith('/collab')) return;-- console.info(- `[collab] upgrade received url=${req.url} protocol=${req.headers['sec-websocket-protocol'] ?? 'none'} host=${req.headers.host ?? 'none'} origin=${req.headers.origin ?? 'none'}`,- );-- // ACP agent-thread frames — bare WS, never Hocuspocus. Mirrors the- // `/collab/thread` branch in mcp-mount.ts (drift hazard: keep both).- if (req.url.startsWith('/collab/thread')) {- if (acpThreadManager === null) {- socket.destroy();- return;- }- socket.on('error', (err: NodeJS.ErrnoException) => {- if (handleCollabSocketError(err)) return;- console.error('[collab] ACP thread socket error:', err);- });- try {- wss.handleUpgrade(req, socket, head, (ws) => {- attachAcpThreadSocket(ws, acpThreadManager, getLogger('acp-threads'));- });- } catch (err) {- console.error(`[collab] thread handleUpgrade threw for ${req.url}:`, err);- try {- socket.destroy();- } catch {- // Already-destroyed — swallow.- }- }- return;- }-- // `ok mcp` holds a persistent WS to /collab/keepalive?connectionId=<id>- // to register as an active client. Must route as a bare WS — MCP- // never sends sync-step-1 that Hocuspocus waits for, so routing- // through hocuspocus.handleConnection would leave the socket- // half-initialized in the connection registry.- if (req.url.startsWith('/collab/keepalive')) {- socket.on('error', (err: NodeJS.ErrnoException) => {- if (handleCollabSocketError(err)) return;- console.error('[collab] MCP keepalive socket error:', err);- });- console.info(`[collab] keepalive handleUpgrade starting for ${req.url}`);- try {- wss.handleUpgrade(req, socket, head, (ws) => {- // connectionId drives cleanup of agent sessions + focus +- // presence. Legacy clients without it fall through to the- // client-side 5s TTL filter.- const connectionId = parseKeepaliveConnectionId(req.url);-- if (connectionId) {- const existing = keepaliveGraceTimers.get(connectionId);- if (existing !== undefined) {- clearTimeout(existing);- keepaliveGraceTimers.delete(connectionId);- console.info(- `[keepalive] reconnect during grace — timer cancelled connectionId=${connectionId}`,- );- }- }-- console.info(`[collab] keepalive handshake complete for ${req.url}`);-- const pingTimer = setInterval(() => {- try {- ws.ping();- } catch {- // Dead socket fires 'close' + 'error' which clean up below.- }- }, 30_000);- pingTimer.unref?.();-- // Client-side TTL filter hides presence entries older than 5s.- // Write-path calls only fire on MCP edits, so agents between- // tool calls (LLM thinking 10-30s) would drop off without this- // 3s bump.- // `toBroadcasterKey` converts the raw URL id into the- // `agent-<id>` map key used by HTTP write handlers; without- // it, `bumpPresenceTs` no-ops because the entry lives under- // the prefixed key.- const tsRefreshTimer = connectionId- ? setInterval(() => {- agentPresenceBroadcaster?.bumpPresenceTs(toBroadcasterKey(connectionId));- }, 3_000)- : null;- tsRefreshTimer?.unref?.();-- ws.on('close', () => {- clearInterval(pingTimer);- if (tsRefreshTimer !== null) clearInterval(tsRefreshTimer);- if (!connectionId) return;- const timer = setTimeout(() => {- keepaliveGraceTimers.delete(connectionId);- // If destroy already ran, the sessionManager +- // broadcasters may be mid-teardown. Racing them is worse- // than skipping cleanup.- if (shuttingDown) return;- const work = (async () => {- console.info(- `[keepalive] grace expired — cleaning up sessions connectionId=${connectionId}`,- );- try {- await sessionManager.closeAllForAgent(connectionId);- } catch (err) {- console.error(- `[keepalive] closeAllForAgent failed connectionId=${connectionId}`,- err,- );- }- try {- agentFocusBroadcaster?.clearFocus(connectionId);- } catch (err) {- console.error(- `[keepalive] clearFocus failed connectionId=${connectionId}`,- err,- );- }- try {- agentPresenceBroadcaster?.clearPresence(toBroadcasterKey(connectionId));- } catch (err) {- console.error(- `[keepalive] clearPresence failed connectionId=${connectionId}`,- err,- );- }- })();- keepaliveGraceInflight.add(work);- work.finally(() => keepaliveGraceInflight.delete(work));- }, KEEPALIVE_GRACE_MS);- timer.unref?.();- keepaliveGraceTimers.set(connectionId, timer);- console.info(- `[keepalive] disconnected — grace timer started connectionId=${connectionId} graceMs=${KEEPALIVE_GRACE_MS}`,- );- });- ws.on('error', (err: NodeJS.ErrnoException) => {- if (!handleCollabSocketError(err)) {- console.error('[collab] keepalive WS error:', err);- }- ws.terminate();- });- });- } catch (err) {- console.error(`[collab] keepalive handleUpgrade threw for ${req.url}:`, err);- try {- socket.destroy();- } catch {- // Already-destroyed sockets throw on destroy; swallow.- }- }- return;- }-- // /collab — browser HocuspocusProvider connections. The socket error- // handler attaches BEFORE handleUpgrade because ECONNRESET during- // the upgrade handshake fires asynchronously with no listener, which- // crashes the whole Node process (see websockets/ws#1017).- socket.on('error', (err: NodeJS.ErrnoException) => {- if (handleCollabSocketError(err)) return;- console.error('[collab] Upgrade socket error:', err);- });-- console.info(`[collab] handleUpgrade starting for ${req.url}`);-- try {- wss.handleUpgrade(req, socket, head, (ws) => {- const beforeCount = hocuspocus.getConnectionsCount?.() ?? -1;- console.info(- `[collab] handshake complete for ${req.url} (connections before=${beforeCount})`,- );- const clientConnection = hocuspocus.handleConnection(ws, req);- let closedByPolicy = false;- ws.on('message', (data: ArrayBuffer | Buffer) => {- if (closedByPolicy) return;- if (data.byteLength > MAX_COLLAB_MESSAGE_BYTES) {- closedByPolicy = true;- console.warn(- `[collab] frame rejected: ${data.byteLength} bytes exceeds ${MAX_COLLAB_MESSAGE_BYTES} byte limit`,- );- ws.close(1009, 'Message Too Big');- return;- }- clientConnection.handleMessage(new Uint8Array(data as Buffer));- });- ws.on('close', (code: number, reason: Buffer) => {- clientConnection.handleClose({ code, reason: reason.toString() });- });- ws.on('error', (err: NodeJS.ErrnoException) => {- if (!handleCollabSocketError(err)) {- console.error('[collab] WebSocket error:', err);- }- ws.terminate();- });- });- } catch (err) {- console.error(`[collab] handleUpgrade threw for ${req.url}:`, err);- try {- socket.destroy();- } catch {- // Already-destroyed — swallow.- }- }+ const collaborationHost = createCollaborationHost({+ hocuspocus,+ log: getLogger('hocuspocus'),+ sessionManager,+ agentFocusBroadcaster,+ agentPresenceBroadcaster,+ maintenanceCoordinator: currentSrv.maintenanceCoordinator,+ acpThreadManager,});+ server.httpServer?.prependListener('upgrade', collaborationHost.handleUpgrade);// Asset-serve middleware — sirv + Content-Disposition dispatch +// fail-closed 404 guard. Policy rationale + branch diagram lives@@ -560,29 +390,37 @@ export function hocuspocusPlugin(): Plugin {next();});- // Close handler is pinned to THIS invocation's `currentSrv` so each- // configureServer pass destroys the srv it created — Vite restart- // semantics (close the old httpServer AFTER the new one has wired- // up) made a module-scope `srv` reference race with itself.- server.httpServer?.on('close', async () => {- shuttingDown = true;- for (const timer of keepaliveGraceTimers.values()) {- clearTimeout(timer);- }- keepaliveGraceTimers.clear();- if (keepaliveGraceInflight.size > 0) {- await Promise.allSettled(keepaliveGraceInflight);- }- try {- await acpThreadManager?.destroy();- } catch (err) {- console.error('[hocuspocus] acpThreadManager.destroy() failed:', err);- }- try {- await currentSrv.destroy();- } catch (err) {- console.error('[hocuspocus] srv.destroy() failed:', err);- }+ let teardownPromise: Promise<void> | undefined;+ const teardown = (): Promise<void> => {+ teardownPromise ??= (async () => {+ const errors: unknown[] = [];+ const run = async (label: string, action: () => Promise<void>): Promise<void> => {+ try {+ await action();+ } catch (err) {+ errors.push(err);+ getLogger('hocuspocus').error(+ { err },+ `Vite collaboration teardown failed: ${label}`,+ );+ }+ };+ server.httpServer?.off('upgrade', collaborationHost.handleUpgrade);+ await run('ACP thread manager', async () => acpThreadManager?.destroy());+ await run('collaboration host', () => collaborationHost.shutdown());+ await run('WebSocket server', () => closeWebSocketServer(collaborationHost.wss));+ await run('server instance', () => currentSrv.destroy());+ if (errors.length > 0)+ throw new AggregateError(errors, 'Vite collaboration teardown failed');+ })();+ void teardownPromise.finally(() => activeRuntimeTeardowns.delete(teardown)).catch(() => {});+ return teardownPromise;+ };+ activeRuntimeTeardowns.add(teardown);+ server.httpServer?.on('close', () => {+ void teardown().catch((err) =>+ getLogger('hocuspocus').error({ err }, 'HTTP close fallback teardown failed'),+ );});getLogger('hocuspocus').info({}, 'WebSocket server ready on /collab');diff --git a/packages/server/src/collaboration-host.test.ts b/packages/server/src/collaboration-host.test.tsnew file mode 100644index 000000000..f18e0b8f0--- /dev/null+++ b/packages/server/src/collaboration-host.test.ts@@ -0,0 +1,435 @@+import { EventEmitter } from 'node:events';+import { createServer } from 'node:http';+import { afterEach, describe, expect, test, vi } from 'vitest';+import { WebSocket } from 'ws';+import { createCollaborationHost } from './collaboration-host.ts';++function createLog() {+ return {+ error: vi.fn(),+ warn: vi.fn(),+ info: vi.fn(),+ debug: vi.fn(),+ } as never;+}++function createSocket() {+ const value = new EventEmitter() as EventEmitter & { destroy: ReturnType<typeof vi.fn> };+ value.destroy = vi.fn(() => value.emit('close'));+ return value;+}++function request(url: string, host = 'localhost', origin?: string) {+ return {+ url,+ headers: { host, ...(origin === undefined ? {} : { origin }) },+ socket: { remoteAddress: '127.0.0.1' },+ } as never;+}++function createHocuspocus() {+ return {+ handleConnection: vi.fn(() => ({ handleMessage: vi.fn(), handleClose: vi.fn() })),+ getConnectionsCount: vi.fn(() => 0),+ } as never;+}++function callbackUpgrade(host: ReturnType<typeof createCollaborationHost>, ws: EventEmitter): void {+ vi.spyOn(host.wss, 'handleUpgrade').mockImplementation((_req, _socket, _head, callback) => {+ callback(ws as never);+ return host.wss;+ });+}++async function withTimeout<T>(promise: Promise<T>, ms = 2_000): Promise<T> {+ let timer: ReturnType<typeof setTimeout> | undefined;+ try {+ return await Promise.race([+ promise,+ new Promise<T>((_resolve, reject) => {+ timer = setTimeout(() => reject(new Error('timed out')), ms);+ }),+ ]);+ } finally {+ if (timer !== undefined) clearTimeout(timer);+ }+}++const closers: Array<() => Promise<void>> = [];+afterEach(async () => {+ await Promise.allSettled(closers.splice(0).map((close) => close()));+ vi.restoreAllMocks();+});++describe('createCollaborationHost', () => {+ test('leaves non-collaboration upgrades completely untouched', () => {+ const log = createLog();+ const host = createCollaborationHost({ hocuspocus: createHocuspocus(), log });+ const raw = createSocket();++ expect(host.handleUpgrade(request('/vite-hmr'), raw as never, Buffer.alloc(0))).toBe(false);+ expect(raw.destroy).not.toHaveBeenCalled();+ expect(raw.listenerCount('error')).toBe(0);+ expect(log.error).not.toHaveBeenCalled();+ expect(log.warn).not.toHaveBeenCalled();+ expect(log.info).not.toHaveBeenCalled();+ expect(log.debug).not.toHaveBeenCalled();+ });++ test('routes thread then keepalive before bare collaboration', () => {+ const log = createLog();+ const hocuspocus = createHocuspocus();+ const host = createCollaborationHost({ hocuspocus, log, acpThreadManager: null });+ const thread = createSocket();+ expect(host.handleUpgrade(request('/collab/thread'), thread as never, Buffer.alloc(0))).toBe(+ true,+ );+ expect(thread.destroy).toHaveBeenCalledOnce();++ const keepaliveWs = new EventEmitter();+ callbackUpgrade(host, keepaliveWs);+ const keepalive = createSocket();+ expect(+ host.handleUpgrade(request('/collab/keepalive'), keepalive as never, Buffer.alloc(0)),+ ).toBe(true);++ const bareWs = new EventEmitter();+ callbackUpgrade(host, bareWs);+ const bare = createSocket();+ expect(host.handleUpgrade(request('/collab'), bare as never, Buffer.alloc(0))).toBe(true);+ expect(hocuspocus.handleConnection).toHaveBeenCalledOnce();+ });++ test('routes an admitted thread socket without forwarding it to Hocuspocus', () => {+ const log = createLog();+ const hocuspocus = createHocuspocus();+ const host = createCollaborationHost({+ hocuspocus,+ log,+ acpThreadManager: {} as never,+ });+ const threadWs = new EventEmitter() as EventEmitter & {+ close: () => void;+ send: () => void;+ };+ threadWs.close = () => {};+ threadWs.send = () => {};+ callbackUpgrade(host, threadWs);++ expect(+ host.handleUpgrade(request('/collab/thread'), createSocket() as never, Buffer.alloc(0)),+ ).toBe(true);+ expect(threadWs.listenerCount('message')).toBe(1);+ expect(hocuspocus.handleConnection).not.toHaveBeenCalled();+ });++ test('refuses local bad Host and foreign thread Origin', () => {+ const log = createLog();+ const host = createCollaborationHost({+ hocuspocus: createHocuspocus(),+ log,+ acpThreadManager: {} as never,+ });+ const badThread = createSocket();+ const badKeepalive = createSocket();+ const foreignOrigin = createSocket();++ host.handleUpgrade(+ request('/collab/thread', 'evil.example'),+ badThread as never,+ Buffer.alloc(0),+ );+ host.handleUpgrade(+ request('/collab/keepalive', 'evil.example'),+ badKeepalive as never,+ Buffer.alloc(0),+ );+ host.handleUpgrade(+ request('/collab/thread', 'localhost', 'https://evil.example'),+ foreignOrigin as never,+ Buffer.alloc(0),+ );+ expect(badThread.destroy).toHaveBeenCalledOnce();+ expect(badKeepalive.destroy).toHaveBeenCalledOnce();+ expect(foreignOrigin.destroy).toHaveBeenCalledOnce();+ });++ test('refuses forwarded bare collaboration upgrades when remote access is disabled', () => {+ const log = createLog();+ const hocuspocus = createHocuspocus();+ const host = createCollaborationHost({ hocuspocus, log });+ const raw = createSocket();+ const forwardedRequest = request('/collab') as {+ headers: Record<string, string>;+ };+ forwardedRequest.headers['x-forwarded-for'] = '203.0.113.7';++ expect(host.handleUpgrade(forwardedRequest as never, raw as never, Buffer.alloc(0))).toBe(true);+ expect(raw.destroy).toHaveBeenCalledOnce();+ expect(hocuspocus.handleConnection).not.toHaveBeenCalled();+ expect(log.warn).toHaveBeenCalledWith(+ { url: '/collab', host: 'localhost' },+ '[remote] refused proxied WS upgrade; start the server with `ok start --remote <url>`',+ );+ });++ test('uses remote access admission for bare collaboration upgrades', () => {+ const log = createLog();+ const hocuspocus = createHocuspocus();+ const host = createCollaborationHost({+ hocuspocus,+ log,+ remoteAccess: {+ url: 'https://myproject.ngrok.app',+ publicHost: 'myproject.ngrok.app',+ port: 24_550,+ },+ });+ const admittedWs = new EventEmitter();+ callbackUpgrade(host, admittedWs);+ const admitted = createSocket();+ const refused = createSocket();++ expect(+ host.handleUpgrade(+ request('/collab', 'myproject.ngrok.app'),+ admitted as never,+ Buffer.alloc(0),+ ),+ ).toBe(true);+ expect(+ host.handleUpgrade(request('/collab', 'evil.example'), refused as never, Buffer.alloc(0)),+ ).toBe(true);+ expect(hocuspocus.handleConnection).toHaveBeenCalledOnce();+ expect(admitted.destroy).not.toHaveBeenCalled();+ expect(refused.destroy).toHaveBeenCalledOnce();+ });++ test('bootstraps presence only for a complete valid keepalive identity', () => {+ const log = createLog();+ const setPresence = vi.fn();+ const host = createCollaborationHost({+ hocuspocus: createHocuspocus(),+ log,+ agentPresenceBroadcaster: { setPresence } as never,+ });+ const validWs = new EventEmitter();+ callbackUpgrade(host, validWs);+ host.handleUpgrade(+ request(+ '/collab/keepalive?connectionId=agent_1&displayName=Agent&clientName=Claude&colorSeed=seed',+ ),+ createSocket() as never,+ Buffer.alloc(0),+ );+ const invalidWs = new EventEmitter();+ callbackUpgrade(host, invalidWs);+ host.handleUpgrade(+ request('/collab/keepalive?connectionId=bad%0Aid&displayName=Agent&clientName=Claude'),+ createSocket() as never,+ Buffer.alloc(0),+ );+ expect(setPresence).toHaveBeenCalledOnce();+ expect(setPresence).toHaveBeenCalledWith(+ 'agent-agent_1',+ expect.objectContaining({ displayName: 'Agent' }),+ );+ });++ test('closes an oversized collaboration message with policy code 1009', () => {+ const handleMessage = vi.fn();+ const hocuspocus = {+ handleConnection: vi.fn(() => ({ handleMessage, handleClose: vi.fn() })),+ getConnectionsCount: vi.fn(() => 0),+ } as never;+ const host = createCollaborationHost({ hocuspocus, log: createLog() });+ const ws = new EventEmitter() as EventEmitter & {+ close: ReturnType<typeof vi.fn>;+ terminate: ReturnType<typeof vi.fn>;+ };+ ws.close = vi.fn();+ ws.terminate = vi.fn();+ callbackUpgrade(host, ws);++ host.handleUpgrade(request('/collab'), createSocket() as never, Buffer.alloc(0));+ ws.emit('message', Buffer.alloc(1024 * 1024 + 1));++ expect(ws.close).toHaveBeenCalledWith(1009, 'Message Too Big');+ expect(handleMessage).not.toHaveBeenCalled();+ });++ test('routes unsupported-length WebSocket errors through the oversized-message path', () => {+ const log = createLog();+ const host = createCollaborationHost({ hocuspocus: createHocuspocus(), log });+ const ws = new EventEmitter() as EventEmitter & {+ terminate: ReturnType<typeof vi.fn>;+ };+ ws.terminate = vi.fn();+ callbackUpgrade(host, ws);+ host.handleUpgrade(request('/collab'), createSocket() as never, Buffer.alloc(0));++ ws.emit(+ 'error',+ Object.assign(new Error('Max payload size exceeded'), {+ code: 'WS_ERR_UNSUPPORTED_MESSAGE_LENGTH',+ }),+ );++ expect(log.warn).toHaveBeenCalledWith(+ {+ event: 'collab-message-too-large',+ limit: 1024 * 1024,+ },+ 'Collab WebSocket frame rejected by ws maxPayload before Yjs processing',+ );+ expect(log.error).not.toHaveBeenCalled();+ expect(ws.terminate).toHaveBeenCalledOnce();+ });++ test('cancels keepalive cleanup when the same connection reconnects during grace', async () => {+ vi.useFakeTimers();+ try {+ const closeAllForAgent = vi.fn();+ const host = createCollaborationHost({+ hocuspocus: createHocuspocus(),+ log: createLog(),+ sessionManager: { closeAllForAgent } as never,+ keepaliveGraceMs: 1_000,+ });+ const firstWs = new EventEmitter();+ callbackUpgrade(host, firstWs);+ host.handleUpgrade(+ request('/collab/keepalive?connectionId=agent1'),+ createSocket() as never,+ Buffer.alloc(0),+ );+ firstWs.emit('close');++ const secondWs = new EventEmitter();+ callbackUpgrade(host, secondWs);+ host.handleUpgrade(+ request('/collab/keepalive?connectionId=agent1'),+ createSocket() as never,+ Buffer.alloc(0),+ );+ await vi.advanceTimersByTimeAsync(1_000);++ expect(closeAllForAgent).not.toHaveBeenCalled();+ await host.shutdown();+ secondWs.emit('close');+ } finally {+ vi.useRealTimers();+ }+ });++ test('contains synchronous upgrade throws and destroys the raw socket', () => {+ const log = createLog();+ const host = createCollaborationHost({ hocuspocus: createHocuspocus(), log });+ vi.spyOn(host.wss, 'handleUpgrade').mockImplementation(() => {+ throw new Error('upgrade failed');+ });+ const raw = createSocket();++ expect(host.handleUpgrade(request('/collab'), raw as never, Buffer.alloc(0))).toBe(true);+ expect(raw.destroy).toHaveBeenCalledOnce();+ expect(log.error).toHaveBeenCalledWith(+ expect.objectContaining({ err: expect.any(Error) }),+ expect.any(String),+ );+ });++ test('shares shutdown, drains sockets, cancels grace work, and awaits active cleanup', async () => {+ const log = createLog();+ const closeAllForAgent = vi.fn();+ const cleanup = Promise.withResolvers<void>();+ closeAllForAgent.mockReturnValue(cleanup.promise);+ const host = createCollaborationHost({+ hocuspocus: createHocuspocus(),+ log,+ sessionManager: { closeAllForAgent } as never,+ keepaliveGraceMs: 0,+ });+ const keepaliveWs = new EventEmitter();+ callbackUpgrade(host, keepaliveWs);+ const keepaliveRaw = createSocket();+ host.handleUpgrade(+ request('/collab/keepalive?connectionId=agent1'),+ keepaliveRaw as never,+ Buffer.alloc(0),+ );+ const bareWs = new EventEmitter();+ callbackUpgrade(host, bareWs);+ const bareRaw = createSocket();+ host.handleUpgrade(request('/collab'), bareRaw as never, Buffer.alloc(0));++ keepaliveWs.emit('close');+ await new Promise((resolve) => setTimeout(resolve, 0));+ expect(closeAllForAgent).toHaveBeenCalledOnce();+ const first = host.shutdown();+ expect(host.shutdown()).toBe(first);+ keepaliveWs.emit('close');+ expect(keepaliveRaw.destroy).toHaveBeenCalled();+ expect(bareRaw.destroy).toHaveBeenCalled();+ let settled = false;+ void first.then(() => {+ settled = true;+ });+ await Promise.resolve();+ expect(settled).toBe(false);+ cleanup.resolve();+ await first;+ });++ test('cancels a pending keepalive grace timer during shutdown', async () => {+ vi.useFakeTimers();+ const closeAllForAgent = vi.fn();+ const host = createCollaborationHost({+ hocuspocus: createHocuspocus(),+ log: createLog(),+ sessionManager: { closeAllForAgent } as never,+ keepaliveGraceMs: 1_000,+ });+ const keepaliveWs = new EventEmitter();+ callbackUpgrade(host, keepaliveWs);+ host.handleUpgrade(+ request('/collab/keepalive?connectionId=agent1'),+ createSocket() as never,+ Buffer.alloc(0),+ );++ keepaliveWs.emit('close');+ await host.shutdown();+ await vi.advanceTimersByTimeAsync(1_000);++ expect(closeAllForAgent).not.toHaveBeenCalled();+ vi.useRealTimers();+ });++ test('allows HTTP and WSS close after draining a live upgraded socket', async () => {+ const log = createLog();+ const hocuspocus = createHocuspocus();+ const host = createCollaborationHost({ hocuspocus, log });+ const httpServer = createServer();+ httpServer.on('upgrade', (req, socket, head) => host.handleUpgrade(req, socket, head));+ await new Promise<void>((resolve) => httpServer.listen(0, '127.0.0.1', resolve));+ const address = httpServer.address();+ if (typeof address !== 'object' || address === null) throw new Error('missing test port');+ const client = new WebSocket(`ws://127.0.0.1:${address.port}/collab`);+ await new Promise<void>((resolve, reject) => {+ client.once('open', resolve);+ client.once('error', reject);+ });+ closers.push(async () => {+ client.terminate();+ await host.shutdown();+ await new Promise<void>((resolve) => host.wss.close(() => resolve()));+ await new Promise<void>((resolve) => httpServer.close(() => resolve()));+ });++ await withTimeout(host.shutdown());+ await withTimeout(new Promise<void>((resolve) => host.wss.close(() => resolve())));+ await withTimeout(new Promise<void>((resolve) => httpServer.close(() => resolve())));+ client.terminate();+ expect(hocuspocus.handleConnection).toHaveBeenCalledOnce();+ });+});diff --git a/packages/server/src/collaboration-host.ts b/packages/server/src/collaboration-host.tsnew file mode 100644index 000000000..5e36984b4--- /dev/null+++ b/packages/server/src/collaboration-host.ts@@ -0,0 +1,366 @@+import type { IncomingMessage } from 'node:http';+import type { Duplex } from 'node:stream';+import type { Hocuspocus } from '@hocuspocus/server';+import { AGENT_ICON_COLORS, colorFromSeed, iconFromClientName } from '@inkeep/open-knowledge-core';+import { WebSocketServer } from 'ws';+import type { AcpThreadManager } from './acp/thread-manager.ts';+import { attachAcpThreadSocket } from './acp/thread-socket.ts';+import type { AgentFocusBroadcaster } from './agent-focus.ts';+import { toBroadcasterKey, validateAgentId } from './agent-id.ts';+import type { AgentPresenceBroadcaster } from './agent-presence.ts';+import type { AgentSessionManager } from './agent-sessions.ts';+import { isAllowedApiOrigin } from './api-origin.ts';+import type { PinoLogger } from './logger.ts';+import { isAllowedWorkspaceHostHeader, isLoopbackAddress } from './loopback.ts';+import type { MaintenanceCoordinator } from './maintenance-coordinator.ts';+import { handleCollabSocketError, incrementCollabMessageTooLarge } from './metrics.ts';+import {+ hasForwardingHeaders,+ isRemoteAdmitted,+ type ResolvedRemoteAccess,+} from './remote-access.ts';++const DEFAULT_KEEPALIVE_GRACE_MS = 10_000;+const MAX_COLLAB_MESSAGE_BYTES = 1024 * 1024;+const MAX_KEEPALIVE_IDENTITY_LEN = 256;++export interface CollaborationHostOptions {+ hocuspocus: Hocuspocus;+ log: PinoLogger;+ sessionManager?: AgentSessionManager;+ agentFocusBroadcaster?: AgentFocusBroadcaster | null;+ agentPresenceBroadcaster?: AgentPresenceBroadcaster | null;+ maintenanceCoordinator?: MaintenanceCoordinator;+ keepaliveGraceMs?: number;+ acpThreadManager?: AcpThreadManager | null;+ remoteAccess?: ResolvedRemoteAccess | null;+}++export interface CollaborationHost {+ readonly wss: WebSocketServer;+ readonly handleUpgrade: (req: IncomingMessage, socket: Duplex, head: Buffer) => boolean;+ shutdown(): Promise<void>;+}++export interface KeepaliveIdentity {+ displayName: string;+ clientName: string;+ colorSeed: string;+}++export function parseKeepaliveConnectionId(url: string | undefined): string | null {+ if (!url) return null;+ try {+ return validateAgentId(new URL(url, 'http://localhost').searchParams.get('connectionId'));+ } catch {+ return null;+ }+}++function sanitizeIdentityField(raw: string | null): string | null {+ if (raw === null || raw.length === 0 || raw.length > MAX_KEEPALIVE_IDENTITY_LEN) return null;+ // biome-ignore lint/suspicious/noControlCharactersInRegex: rejects control characters in awareness values+ return /[\u0000-\u001f\u007f]/.test(raw) ? null : raw;+}++export function parseKeepaliveIdentity(url: string | undefined): KeepaliveIdentity | null {+ if (!url) return null;+ try {+ const parsed = new URL(url, 'http://localhost');+ const displayName = sanitizeIdentityField(parsed.searchParams.get('displayName'));+ const clientName = sanitizeIdentityField(parsed.searchParams.get('clientName'));+ const colorSeed = sanitizeIdentityField(parsed.searchParams.get('colorSeed'));+ return displayName === null || clientName === null || colorSeed === null+ ? null+ : { displayName, clientName, colorSeed };+ } catch {+ return null;+ }+}++export function createCollaborationHost(options: CollaborationHostOptions): CollaborationHost {+ const {+ hocuspocus,+ log,+ sessionManager,+ agentFocusBroadcaster,+ agentPresenceBroadcaster,+ maintenanceCoordinator,+ acpThreadManager,+ } = options;+ const remoteAccess = options.remoteAccess ?? undefined;+ const keepaliveGraceMs = options.keepaliveGraceMs ?? DEFAULT_KEEPALIVE_GRACE_MS;+ const wss = new WebSocketServer({ noServer: true, maxPayload: MAX_COLLAB_MESSAGE_BYTES });+ const keepaliveGraceTimers = new Map<string, ReturnType<typeof setTimeout>>();+ const keepaliveGraceInflight = new Set<Promise<void>>();+ const liveUpgradeSockets = new Set<Duplex>();+ let shuttingDown = false;+ let shutdownPromise: Promise<void> | undefined;++ wss.on('error', (err) => log.error({ err }, 'WebSocketServer error'));++ const admitted = (req: IncomingMessage): boolean =>+ remoteAccess !== undefined+ ? isRemoteAdmitted(req, remoteAccess)+ : isLoopbackAddress(req.socket.remoteAddress) &&+ isAllowedWorkspaceHostHeader(req.headers.host);++ const trackSocket = (socket: Duplex, label: string): void => {+ socket.on('error', (err: NodeJS.ErrnoException) => {+ if (!handleCollabSocketError(err)) log.error({ err }, `${label} socket error`);+ });+ liveUpgradeSockets.add(socket);+ socket.once('close', () => liveUpgradeSockets.delete(socket));+ };++ const safelyHandleUpgrade = (+ req: IncomingMessage,+ socket: Duplex,+ head: Buffer,+ label: string,+ onConnection: Parameters<WebSocketServer['handleUpgrade']>[3],+ ): void => {+ try {+ wss.handleUpgrade(req, socket, head, onConnection);+ } catch (err) {+ log.error({ err, url: req.url }, `[collab] ${label} handleUpgrade threw`);+ try {+ socket.destroy();+ } catch {+ // Best effort for an already-destroyed upgrade socket.+ }+ }+ };++ const handleKeepalive = (req: IncomingMessage, socket: Duplex, head: Buffer): void => {+ if (!admitted(req)) {+ log.debug(+ { url: req.url, host: req.headers.host },+ '[collab] /collab/keepalive upgrade refused',+ );+ socket.destroy();+ return;+ }+ trackSocket(socket, 'MCP keepalive');+ safelyHandleUpgrade(req, socket, head, 'keepalive', (ws) => {+ const connectionId = parseKeepaliveConnectionId(req.url);+ if (connectionId) {+ const existing = keepaliveGraceTimers.get(connectionId);+ if (existing !== undefined) {+ clearTimeout(existing);+ keepaliveGraceTimers.delete(connectionId);+ log.info({ connectionId }, '[keepalive] reconnect during grace — timer cancelled');+ }+ }+ if (connectionId && agentPresenceBroadcaster) {+ const identity = parseKeepaliveIdentity(req.url);+ if (identity) {+ try {+ const icon = iconFromClientName(identity.clientName);+ agentPresenceBroadcaster.setPresence(toBroadcasterKey(connectionId), {+ displayName: identity.displayName,+ icon,+ color: AGENT_ICON_COLORS[icon] ?? colorFromSeed(identity.colorSeed),+ // Presence filtering hides entries without `currentDoc`; this+ // non-document sentinel surfaces the agent before its first write.+ currentDoc: '(connected)',+ mode: 'idle',+ ts: Date.now(),+ });+ } catch (err) {+ log.error({ err, connectionId }, '[keepalive] presence bootstrap failed');+ }+ }+ }+ const pingTimer = setInterval(() => {+ try {+ ws.ping();+ } catch {+ // The close/error callbacks dispose the dead socket.+ }+ }, 30_000);+ pingTimer.unref?.();+ // Refresh faster than the client-side 5 s TTL so an idle agent stays+ // visible between tool calls. Presence lives under `agent-<id>`; using+ // the raw URL id would make `bumpPresenceTs` a no-op.+ const tsRefreshTimer = connectionId+ ? setInterval(+ () => agentPresenceBroadcaster?.bumpPresenceTs(toBroadcasterKey(connectionId)),+ 3_000,+ )+ : null;+ tsRefreshTimer?.unref?.();+ ws.on('close', () => {+ clearInterval(pingTimer);+ if (tsRefreshTimer !== null) clearInterval(tsRefreshTimer);+ if (!connectionId || shuttingDown) return;+ const timer = setTimeout(() => {+ keepaliveGraceTimers.delete(connectionId);+ // Shutdown may begin after this timer is scheduled but before it+ // fires; never race cleanup against session and broadcaster teardown.+ if (shuttingDown) return;+ const work = (async () => {+ log.info({ connectionId }, '[keepalive] grace expired — cleaning up sessions');+ try {+ await sessionManager?.closeAllForAgent(connectionId);+ } catch (err) {+ log.error({ err, connectionId }, '[keepalive] closeAllForAgent failed');+ }+ try {+ agentFocusBroadcaster?.clearFocus(connectionId);+ } catch (err) {+ log.error({ err, connectionId }, '[keepalive] clearFocus failed');+ }+ try {+ agentPresenceBroadcaster?.clearPresence(toBroadcasterKey(connectionId));+ } catch (err) {+ log.error({ err, connectionId }, '[keepalive] clearPresence failed');+ }+ // A closed keepalive means its writer is dead, so maintenance can+ // evaluate off the write path. Flush-counter and boot maintenance+ // reap other session types; only `session-close` telemetry is+ // intentionally limited to keepalive-backed sessions.+ try {+ await maintenanceCoordinator?.onSessionClose();+ } catch (err) {+ log.error({ err, connectionId }, '[keepalive] maintenance onSessionClose failed');+ }+ })();+ keepaliveGraceInflight.add(work);+ void work.finally(() => keepaliveGraceInflight.delete(work));+ }, keepaliveGraceMs);+ timer.unref?.();+ keepaliveGraceTimers.set(connectionId, timer);+ log.info(+ { connectionId, graceMs: keepaliveGraceMs },+ '[keepalive] disconnected — grace timer started',+ );+ });+ ws.on('error', (err: NodeJS.ErrnoException) => {+ if (!handleCollabSocketError(err)) log.error({ err }, 'MCP keepalive WS error');+ ws.terminate();+ });+ });+ };++ const handleUpgrade = (req: IncomingMessage, socket: Duplex, head: Buffer): boolean => {+ if (!req.url?.startsWith('/collab')) return false;+ // These breadcrumbs locate a stalled upgrade: `upgrade received` reached+ // this host, `handleUpgrade starting` passed routing, `handleUpgrade threw`+ // marks a synchronous WS handoff failure, and `handshake complete` means+ // Hocuspocus owns the connection.+ log.info(+ {+ url: req.url,+ protocol: req.headers['sec-websocket-protocol'] ?? 'none',+ host: req.headers.host ?? 'none',+ origin: req.headers.origin ?? 'none',+ },+ '[collab] upgrade received',+ );+ if (remoteAccess === undefined && hasForwardingHeaders(req)) {+ log.warn(+ { url: req.url, host: req.headers.host },+ '[remote] refused proxied WS upgrade; start the server with `ok start --remote <url>`',+ );+ socket.destroy();+ return true;+ }+ if (req.url.startsWith('/collab/thread')) {+ if (+ acpThreadManager === undefined ||+ acpThreadManager === null ||+ !admitted(req) ||+ (req.headers.origin !== undefined &&+ !isAllowedApiOrigin(req.headers.origin, remoteAccess?.publicHost))+ ) {+ log.debug(+ { url: req.url, host: req.headers.host, origin: req.headers.origin },+ '[collab] /collab/thread upgrade refused',+ );+ socket.destroy();+ return true;+ }+ trackSocket(socket, 'ACP thread');+ safelyHandleUpgrade(req, socket, head, 'thread', (ws) =>+ attachAcpThreadSocket(ws, acpThreadManager, log),+ );+ return true;+ }+ if (req.url.startsWith('/collab/keepalive')) {+ handleKeepalive(req, socket, head);+ return true;+ }+ if (remoteAccess !== undefined && !isRemoteAdmitted(req, remoteAccess)) {+ log.debug({ url: req.url, host: req.headers.host }, '[collab] /collab upgrade refused');+ socket.destroy();+ return true;+ }+ trackSocket(socket, 'Upgrade');+ log.info({ url: req.url }, '[collab] handleUpgrade starting');+ safelyHandleUpgrade(req, socket, head, 'collaboration', (ws) => {+ const connectionsBefore = hocuspocus.getConnectionsCount?.() ?? -1;+ const clientConnection = hocuspocus.handleConnection(ws, req as unknown as Request);+ log.info({ url: req.url, connectionsBefore }, '[collab] handshake complete');+ let closedByPolicy = false;+ ws.on('message', (data: ArrayBuffer | Buffer) => {+ if (closedByPolicy) return;+ if (data.byteLength > MAX_COLLAB_MESSAGE_BYTES) {+ closedByPolicy = true;+ incrementCollabMessageTooLarge();+ log.warn(+ {+ event: 'collab-message-too-large',+ bytes: data.byteLength,+ limit: MAX_COLLAB_MESSAGE_BYTES,+ },+ 'Collab WebSocket message rejected before Yjs processing',+ );+ ws.close(1009, 'Message Too Big');+ return;+ }+ clientConnection.handleMessage(new Uint8Array(data as Buffer));+ });+ ws.on('close', (code: number, reason: Buffer) =>+ clientConnection.handleClose({ code, reason: reason.toString() }),+ );+ ws.on('error', (err: NodeJS.ErrnoException) => {+ if (err.code === 'WS_ERR_UNSUPPORTED_MESSAGE_LENGTH') {+ incrementCollabMessageTooLarge();+ log.warn(+ { event: 'collab-message-too-large', limit: MAX_COLLAB_MESSAGE_BYTES },+ 'Collab WebSocket frame rejected by ws maxPayload before Yjs processing',+ );+ } else if (!handleCollabSocketError(err)) {+ log.error({ err }, 'WebSocket error');+ }+ ws.terminate();+ });+ });+ return true;+ };++ const shutdown = (): Promise<void> => {+ shutdownPromise ??= (async () => {+ // Socket destruction emits close events; set the guard first so those+ // callbacks cannot schedule fresh grace cleanup during teardown.+ shuttingDown = true;+ // Callers close WSS/HTTP after this promise. Live upgraded sockets would+ // keep those closes pending, while destroying them also drives WS cleanup.+ for (const socket of liveUpgradeSockets) {+ try {+ socket.destroy();+ } catch {+ /* best effort */+ }+ }+ liveUpgradeSockets.clear();+ for (const timer of keepaliveGraceTimers.values()) clearTimeout(timer);+ keepaliveGraceTimers.clear();+ await Promise.allSettled(keepaliveGraceInflight);+ })();+ return shutdownPromise;+ };++ return { wss, handleUpgrade, shutdown };+}diff --git a/packages/server/src/index.ts b/packages/server/src/index.tsindex c714e2f67..274e3a7e6 100644--- a/packages/server/src/index.ts+++ b/packages/server/src/index.ts@@ -96,6 +96,11 @@ export {type HiddenWindowsConsoleOptions,withHiddenWindowsConsole,} from './child-process-windows-hide.ts';+export {+ type CollaborationHost,+ type CollaborationHostOptions,+ createCollaborationHost,+} from './collaboration-host.ts';export { getLocalDir, resolveContentDir, resolveLockDir } from './config/paths.ts';export { type Config, ConfigSchema } from './config/schema.ts';export { MCP_SERVER_NAME } from './constants.ts';diff --git a/packages/server/src/mcp-mount.test.ts b/packages/server/src/mcp-mount.test.tsindex a14f0a24f..f2a78a841 100644--- a/packages/server/src/mcp-mount.test.ts+++ b/packages/server/src/mcp-mount.test.ts@@ -10,7 +10,7 @@ import {INLINE_RENDERABLE_EXTENSIONS,} from '@inkeep/open-knowledge-core';import sirv from 'sirv';-import { afterEach, describe, expect, test } from 'vitest';+import { afterEach, describe, expect, test, vi } from 'vitest';import { WebSocket } from 'ws';import { createAssetServeMiddleware } from './asset-serve-middleware.ts';import { getFreeLoopbackPort } from './loopback-rig-test-helpers.ts';@@ -23,7 +23,7 @@ import {const log = {error: () => {},- warn: () => {},+ warn: vi.fn(),info: () => {},debug: () => {},child: () => log,@@ -39,18 +39,21 @@ const hocuspocus = {let servers: Array<{ httpServer: HttpServer; mount: MountMcpAndApiHandle }> = [];-async function startMountedServer(handler: McpHttpHandler): Promise<{ port: number }> {+async function startMountedServer(+ handler: McpHttpHandler,+ serverHocuspocus: Hocuspocus = hocuspocus,+): Promise<{ port: number; mount: MountMcpAndApiHandle }> {const httpServer = createServer();const mount = mountMcpAndApi({httpServer,- hocuspocus,+ hocuspocus: serverHocuspocus,mcpHttpHandler: handler,log,});const port = await getFreeLoopbackPort();await new Promise<void>((resolve) => httpServer.listen(port, '127.0.0.1', () => resolve()));servers.push({ httpServer, mount });- return { port };+ return { port, mount };}async function postMcpWithHost(@@ -106,7 +109,11 @@ async function getWithHost(});}-async function requestUnknownUpgrade(port: number): Promise<string> {+async function requestUnknownUpgrade(port: number, forwarding = false): Promise<string> {+ return requestUpgrade(port, '/not-a-websocket-route', forwarding);+}++async function requestUpgrade(port: number, path: string, forwarding = false): Promise<string> {return new Promise((resolve, reject) => {const socket = createNetConnection({ host: '127.0.0.1', port });const chunks: Buffer[] = [];@@ -118,12 +125,13 @@ async function requestUnknownUpgrade(port: number): Promise<string> {socket.on('connect', () => {socket.write([- 'GET /not-a-websocket-route HTTP/1.1',+ `GET ${path} HTTP/1.1`,'Host: 127.0.0.1','Connection: Upgrade','Upgrade: websocket','Sec-WebSocket-Version: 13','Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==',+ ...(forwarding ? ['X-Forwarded-For: 203.0.113.7'] : []),'','',].join('\r\n'),@@ -141,6 +149,34 @@ async function requestUnknownUpgrade(port: number): Promise<string> {});}+async function requestRejectedUpgrade(port: number, path: string): Promise<number> {+ return new Promise((resolve, reject) => {+ const req = httpRequest({+ hostname: '127.0.0.1',+ port,+ path,+ headers: {+ Connection: 'Upgrade',+ Upgrade: 'websocket',+ 'Sec-WebSocket-Version': '13',+ 'Sec-WebSocket-Key': 'dGhlIHNhbXBsZSBub25jZQ==',+ },+ });+ req.on('response', (res) => {+ const status = res.statusCode ?? 0;+ res.resume();+ res.on('end', () => resolve(status));+ });+ req.on('upgrade', (_res, socket) => {+ socket.destroy();+ reject(new Error('upgrade was admitted after shutdown'));+ });+ req.on('error', reject);+ req.setTimeout(1_000, () => req.destroy(new Error('timed out waiting for upgrade refusal')));+ req.end();+ });+}+afterEach(async () => {const active = servers;servers = [];@@ -239,6 +275,47 @@ describe('mountMcpAndApi /mcp guard', () => {expect(response).toBe('');expect(calls).toBe(0);});++ test('warns before closing a proxied unknown upgrade', async () => {+ vi.mocked(log.warn).mockClear();+ const { port } = await startMountedServer({ handle: async () => {}, close: async () => {} });++ await expect(requestUnknownUpgrade(port, true)).resolves.toBe('');+ expect(log.warn).toHaveBeenCalledWith(+ expect.objectContaining({ host: '127.0.0.1' }),+ expect.stringContaining('refused proxied WS upgrade'),+ );+ });++ test('shares shutdown and keeps routing attached until the server closes', async () => {+ const handleConnection = vi.fn(() => ({+ handleMessage: () => {},+ handleClose: () => {},+ }));+ const scopedHocuspocus = {+ hooks: async () => {},+ handleConnection,+ } as unknown as Hocuspocus;+ const { port, mount } = await startMountedServer(+ {+ handle: async () => {},+ close: async () => {},+ },+ scopedHocuspocus,+ );+ const first = mount.shutdown();+ expect(mount.shutdown()).toBe(first);+ await first;++ const response = await fetch(`http://127.0.0.1:${port}/still-routed`, {+ signal: AbortSignal.timeout(1_000),+ });+ expect(response.status).toBe(404);++ await expect(requestRejectedUpgrade(port, '/collab')).resolves.toBe(404);+ expect(handleConnection).not.toHaveBeenCalled();+ expect(mount.wss.clients.size).toBe(0);+ });});// Regression: a live `/collab` or `/collab/keepalive` WS that survives intodiff --git a/packages/server/src/mcp-mount.ts b/packages/server/src/mcp-mount.tsindex 0d1ec80c7..dc2e5e3e4 100644--- a/packages/server/src/mcp-mount.ts+++ b/packages/server/src/mcp-mount.ts@@ -1,59 +1,46 @@/**- * `mountMcpAndApi` — single canonical wiring for `/mcp` + `/api/*` + WS upgrade.+ * `mountMcpAndApi` is the canonical HTTP adapter for `/mcp`, `/api/*`, content+ * assets, and the optional React shell. `bootServer()` and the integration+ * harnesses use it; Vite owns its Connect middleware and shares only the+ * collaboration host.*- * Three consumers compose the same four ingredients on top of an `http.Server`:- * 1. `bootServer()` (CLI `ok start`, Electron utility, Vite dev plugin via the- * shared boot path).- * 2. The integration test harness's `createTestServer()`.- * 3. The integration test harness's `createRestartableServer()` (no `/mcp` —- * passes `mcpHttpHandler: undefined`).+ * Collaboration WebSocket routing and lifecycle live in+ * `createCollaborationHost()`. This adapter delegates `/collab`,+ * `/collab/keepalive`, and `/collab/thread` upgrades to that host, then owns+ * only the fallback that rejects unknown upgrade paths.*- * Before this extraction every consumer reimplemented the request handler, the- * `WebSocketServer({ noServer: true })`, the `/collab/keepalive` short-circuit,- * the keepalive-grace timer map, and the per-`connectionId` cleanup cascade- * (`closeAllForAgent` + `clearFocus` + `clearPresence`). The duplication had- * already drifted: `boot.ts` validated `connectionId` via `validateAgentId` to- * defend against log-injection / `clearPresence` cross-eviction; the harness- * accepted any `connectionId` query param. Centralizing in one helper closes- * that drift class permanently — every consumer gets the production-grade- * validation path.- *- * The helper attaches both `'request'` and `'upgrade'` listeners to the+ * The adapter attaches both `'request'` and `'upgrade'` listeners to the* supplied `httpServer`. Callers therefore MUST `createHttpServer()` with no* constructor callback — passing a `(req, res) => {…}` arg would install a* second `'request'` listener and double-handle every inbound HTTP request.*- * `shutdown()` cancels pending grace timers + awaits in-flight cleanups so- * caller `destroy()` paths do not race a still-firing grace callback into- * a torn-down `sessionManager` / broadcaster.+ * `shutdown()` leaves request routing attached until the caller closes the HTTP+ * server so requests do not silently hang during later teardown phases. It+ * detaches upgrades before draining the collaboration host so no new WebSocket+ * can escape that one-shot drain.*/import type { Server as HttpServer, IncomingMessage, ServerResponse } from 'node:http';import type { Duplex } from 'node:stream';import type { Hocuspocus } from '@hocuspocus/server';-import { AGENT_ICON_COLORS, colorFromSeed, iconFromClientName } from '@inkeep/open-knowledge-core';-import { WebSocketServer } from 'ws';+import type { WebSocketServer } from 'ws';import type { AcpThreadManager } from './acp/thread-manager.ts';-import { attachAcpThreadSocket } from './acp/thread-socket.ts';import type { AgentFocusBroadcaster } from './agent-focus.ts';-import { toBroadcasterKey, validateAgentId } from './agent-id.ts';import type { AgentPresenceBroadcaster } from './agent-presence.ts';import type { AgentSessionManager } from './agent-sessions.ts';import { isAllowedApiOrigin } from './api-origin.ts';+import { createCollaborationHost } from './collaboration-host.ts';import { errorResponse } from './http/error-response.ts';import type { PinoLogger } from './logger.ts';import { isAllowedWorkspaceHostHeader, isLoopbackAddress } from './loopback.ts';import type { MaintenanceCoordinator } from './maintenance-coordinator.ts';import type { McpHttpHandler } from './mcp-http.ts';-import { handleCollabSocketError, incrementCollabMessageTooLarge } from './metrics.ts';import {hasForwardingHeaders,isRemoteAdmitted,type ResolvedRemoteAccess,} from './remote-access.ts';-const DEFAULT_KEEPALIVE_GRACE_MS = 10_000;-const MAX_COLLAB_MESSAGE_BYTES = 1024 * 1024;const MCP_CORS_HEADERS = {'Access-Control-Allow-Methods': 'GET, POST, DELETE, OPTIONS','Access-Control-Allow-Headers':@@ -202,30 +189,19 @@ export function mountMcpAndApi(opts: MountMcpAndApiOptions): MountMcpAndApiHandlephemeral,} = opts;const remoteAccess = opts.remoteAccess ?? undefined;- const keepaliveGraceMs = opts.keepaliveGraceMs ?? DEFAULT_KEEPALIVE_GRACE_MS;- const wss = new WebSocketServer({ noServer: true, maxPayload: MAX_COLLAB_MESSAGE_BYTES });- wss.on('error', (err) => {- log.error({ err }, 'WebSocketServer error');+ const collaborationHost = createCollaborationHost({+ hocuspocus,+ log,+ sessionManager,+ agentFocusBroadcaster,+ agentPresenceBroadcaster,+ maintenanceCoordinator,+ keepaliveGraceMs: opts.keepaliveGraceMs,+ acpThreadManager: opts.acpThreadManager,+ remoteAccess,});- // connectionId → pending grace timer handle.- const keepaliveGraceTimers = new Map<string, ReturnType<typeof setTimeout>>();- // In-flight grace-timer callbacks so `shutdown()` can await them rather than- // racing against the sessionManager / agentFocusBroadcaster teardown.- const keepaliveGraceInflight = new Set<Promise<void>>();- // Raw upgrade sockets (the `Duplex` handed to the `'upgrade'` handler) for- // every live `/collab` + `/collab/keepalive` connection. `shutdown()` destroys- // these so the caller's `wss.close()` / `httpServer.close()` steps resolve —- // an upgraded socket is detached from the HTTP server and `httpServer.close()`- // will not return while one is open, and `httpServer.closeAllConnections()`- // does not reliably reap upgrade-detached sockets across runtimes. Mirrors- // the drain in `cli/src/commands/ui.ts` / `ui-proxy.ts`.- const liveUpgradeSockets = new Set<Duplex>();- // Set when `shutdown()` runs so any callback that fired just before the- // timer was cleared can short-circuit instead of touching disposed resources.- let shuttingDown = false;-const onRequest = (req: IncomingMessage, res: ServerResponse): void => {const url = req.url?.split('?')[0];// Tripwire: proxy-forwarding headers on a server that never opted into@@ -448,311 +424,33 @@ export function mountMcpAndApi(opts: MountMcpAndApiOptions): MountMcpAndApiHandl};const onUpgrade = (req: IncomingMessage, socket: Duplex, head: Buffer): void => {- // Same tripwire as the HTTP leg: a proxied upgrade on a server that never- // opted into remote access is refused rather than trusted as local.+ if (collaborationHost.handleUpgrade(req, socket, head)) return;if (remoteAccess === undefined && hasForwardingHeaders(req)) {log.warn({ url: req.url, host: req.headers.host },'[remote] refused proxied WS upgrade; start the server with `ok start --remote <url>`',);- socket.destroy();- return;- }- // Shared admit decision for the `/collab/thread` + `/collab/keepalive`- // upgrades. Remote mode widens the Host allowlist to the tunnel's public- // host through the `isRemoteAdmitted` choke point (tunnel traffic arrives- // loopback-peer + public-Host); local mode keeps the loopback-peer +- // workspace-Host gate. The bare `/collab` catch-all below relies on the- // loopback bind in local mode, so it only consults `isRemoteAdmitted`.- const collabUpgradeAdmitted = (): boolean =>- remoteAccess !== undefined- ? isRemoteAdmitted(req, remoteAccess)- : isLoopbackAddress(req.socket.remoteAddress) &&- isAllowedWorkspaceHostHeader(req.headers.host);- if (req.url?.startsWith('/collab/thread')) {- // Admit via the shared `/collab` upgrade gate (remote-widened Host in- // remote mode), plus the browser-Origin allowlist when an Origin is- // present (WS upgrades from pages always carry one; a DNS-rebound page- // fails the Host check, a foreign page fails the Origin check).- const acp = opts.acpThreadManager;- if (- acp === undefined ||- acp === null ||- !collabUpgradeAdmitted() ||- (req.headers.origin !== undefined &&- !isAllowedApiOrigin(req.headers.origin, remoteAccess?.publicHost))- ) {- log.debug(- { url: req.url, host: req.headers.host, origin: req.headers.origin },- '[collab] /collab/thread upgrade refused',- );- socket.destroy();- return;- }- socket.on('error', (err: NodeJS.ErrnoException) => {- if (handleCollabSocketError(err)) return;- log.error({ err }, 'ACP thread socket error');- });- liveUpgradeSockets.add(socket);- socket.once('close', () => liveUpgradeSockets.delete(socket));- wss.handleUpgrade(req, socket, head, (ws) => {- attachAcpThreadSocket(ws, acp, log);- });- return;- }-- if (req.url?.startsWith('/collab/keepalive')) {- if (!collabUpgradeAdmitted()) {- log.debug(- { url: req.url, host: req.headers.host },- '[collab] /collab/keepalive upgrade refused',- );- socket.destroy();- return;- }- socket.on('error', (err: NodeJS.ErrnoException) => {- if (handleCollabSocketError(err)) return;- log.error({ err }, 'MCP keepalive socket error');- });- liveUpgradeSockets.add(socket);- socket.once('close', () => liveUpgradeSockets.delete(socket));- wss.handleUpgrade(req, socket, head, (ws) => {- // Per-session connectionId from the URL. Validated through the same- // regex as the HTTP write path (`extractAgentIdentity` in- // `api-extension.ts`) so the keepalive cleanup surface and the write- // surface share one contract — without it a caller who can reach the- // keepalive WS could force-evict another agent's presence by- // crafting `connectionId=<victim>` on close.- const connectionId = parseKeepaliveConnectionId(req.url);-- // Reconnect within the grace window cancels the pending eviction.- if (connectionId) {- const existing = keepaliveGraceTimers.get(connectionId);- if (existing !== undefined) {- clearTimeout(existing);- keepaliveGraceTimers.delete(connectionId);- log.info({ connectionId }, '[keepalive] reconnect during grace — timer cancelled');- }- }-- // Bootstrap a presence entry on connect when the cli's MCP shim- // forwarded full identity in the URL. Without this, `bumpPresenceTs`- // (the 3 s heartbeat below) is a documented no-op until something- // else calls `setPresence` first — which only happens for the four- // mutating HTTP write handlers in `api-extension.ts`. Lifting the- // bootstrap to the WS-upgrade handler makes presence appear on- // every MCP connect, regardless of whether the agent ever issues- // a write tool.- //- // Identity sanitisation lives in `parseKeepaliveIdentity` — log- // injection / awareness pollution surface. Mirrors the helper-chain- // the four handler-level setPresence sites use (iconFromClientName /- // AGENT_ICON_COLORS / colorFromSeed) so the entry shape is- // bit-identical to what a write would have produced.- if (connectionId && agentPresenceBroadcaster) {- const identity = parseKeepaliveIdentity(req.url);- if (identity) {- try {- const icon = iconFromClientName(identity.clientName);- const color = AGENT_ICON_COLORS[icon] ?? colorFromSeed(identity.colorSeed);- agentPresenceBroadcaster.setPresence(toBroadcasterKey(connectionId), {- displayName: identity.displayName,- icon,- color,- // Sentinel `currentDoc` so the badge surfaces in the- // cross-doc bucket — the client filter at- // `packages/app/src/lib/agent-presence.ts` drops entries- // with falsy `currentDoc`, so null would mean the- // bootstrap entry stays hidden until the agent's first- // write. The `(connected)` form is human-readable and- // distinct from any real docName; future click-to-navigate- // handlers can short-circuit on the leading `(`.- currentDoc: '(connected)',- mode: 'idle',- ts: Date.now(),- });- } catch (err) {- log.error({ err, connectionId }, '[keepalive] presence bootstrap failed');- }- }- }-- const pingTimer = setInterval(() => {- try {- ws.ping();- } catch {- // Dead socket fires 'close' + 'error' which clean up below.- }- }, 30_000);- pingTimer.unref?.();-- // Presence-ts heartbeat — beats the client-side 5 s TTL filter when- // an agent sits idle between tool calls (LLM "thinking" 10–30 s).- // `toBroadcasterKey(connectionId)` translates the raw URL id into- // the `agent-<id>` map key used by HTTP write handlers via- // `extractAgentIdentity`; without the prefix `bumpPresenceTs` no-ops- // because no entry lives under the bare key.- const tsRefreshTimer = connectionId- ? setInterval(() => {- agentPresenceBroadcaster?.bumpPresenceTs(toBroadcasterKey(connectionId));- }, 3_000)- : null;- tsRefreshTimer?.unref?.();-- ws.on('close', () => {- clearInterval(pingTimer);- if (tsRefreshTimer !== null) clearInterval(tsRefreshTimer);- if (!connectionId) return;- const timer = setTimeout(() => {- keepaliveGraceTimers.delete(connectionId);- // If `shutdown()` already ran, the sessionManager + broadcasters- // may be mid-teardown — racing them is worse than skipping- // cleanup (TOCTOU between our clearTimeout loop and the timer- // firing).- if (shuttingDown) return;- const work = (async () => {- log.info({ connectionId }, '[keepalive] grace expired — cleaning up sessions');- try {- await sessionManager?.closeAllForAgent(connectionId);- } catch (err) {- log.error({ err, connectionId }, '[keepalive] closeAllForAgent failed');- }- try {- agentFocusBroadcaster?.clearFocus(connectionId);- } catch (err) {- log.error({ err, connectionId }, '[keepalive] clearFocus failed');- }- try {- agentPresenceBroadcaster?.clearPresence(toBroadcasterKey(connectionId));- } catch (err) {- log.error({ err, connectionId }, '[keepalive] clearPresence failed');- }- // The closed session's writer is now dead — evaluate maintenance- // (session-close trigger) off the write path. Gated +- // fire-and-forget; never blocks session teardown.- // Scope: this is the ONLY `session-close`-labelled trigger, so it- // fires only for keepalive-WS sessions. HTTP-only MCP callers,- // direct Hocuspocus connections, and bulk `closeAll()` on shutdown- // don't reach it — their dead chains are still reaped by the- // flush-counter and boot triggers, so coverage is complete; only the- // `session-close` telemetry label under-counts those paths.- try {- await maintenanceCoordinator?.onSessionClose();- } catch (err) {- log.error({ err, connectionId }, '[keepalive] maintenance onSessionClose failed');- }- })();- keepaliveGraceInflight.add(work);- work.finally(() => keepaliveGraceInflight.delete(work));- }, keepaliveGraceMs);- timer.unref?.();- keepaliveGraceTimers.set(connectionId, timer);- log.info(- { connectionId, graceMs: keepaliveGraceMs },- '[keepalive] disconnected — grace timer started',- );- });- ws.on('error', (err: NodeJS.ErrnoException) => {- if (!handleCollabSocketError(err)) {- log.error({ err }, 'MCP keepalive WS error');- }- ws.terminate();- });- });- return;- }-- if (req.url?.startsWith('/collab')) {- // Same admit gate as the HTTP legs: a wrong-Host upgrade never reaches- // Hocuspocus (the CRDT write surface).- if (remoteAccess !== undefined && !isRemoteAdmitted(req, remoteAccess)) {- log.debug({ url: req.url, host: req.headers.host }, '[collab] /collab upgrade refused');- socket.destroy();- return;- }- socket.on('error', (err: NodeJS.ErrnoException) => {- if (handleCollabSocketError(err)) return;- log.error({ err }, 'Upgrade socket error');- });- liveUpgradeSockets.add(socket);- socket.once('close', () => liveUpgradeSockets.delete(socket));- wss.handleUpgrade(req, socket, head, (ws) => {- const clientConnection = hocuspocus.handleConnection(- ws as unknown as WebSocket,- req as unknown as Request,- );- let closedByPolicy = false;- ws.on('message', (data: ArrayBuffer | Buffer) => {- if (closedByPolicy) return;- const bytes = data.byteLength;- if (bytes > MAX_COLLAB_MESSAGE_BYTES) {- closedByPolicy = true;- incrementCollabMessageTooLarge();- log.warn(- { event: 'collab-message-too-large', bytes, limit: MAX_COLLAB_MESSAGE_BYTES },- 'Collab WebSocket message rejected before Yjs processing',- );- ws.close(1009, 'Message Too Big');- return;- }- clientConnection.handleMessage(new Uint8Array(data as Buffer));- });- ws.on('close', (code: number, reason: Buffer) => {- clientConnection.handleClose({ code, reason: reason.toString() });- });- ws.on('error', (err: NodeJS.ErrnoException) => {- if (err.code === 'WS_ERR_UNSUPPORTED_MESSAGE_LENGTH') {- incrementCollabMessageTooLarge();- log.warn(- { event: 'collab-message-too-large', limit: MAX_COLLAB_MESSAGE_BYTES },- 'Collab WebSocket frame rejected by ws maxPayload before Yjs processing',- );- ws.terminate();- return;- }- if (!handleCollabSocketError(err)) {- log.error({ err }, 'WebSocket error');- }- ws.terminate();- });- });- return;}-socket.destroy();};httpServer.on('request', onRequest);httpServer.on('upgrade', onUpgrade);+ let shutdownPromise: Promise<void> | undefined;+ const shutdown = (): Promise<void> => {+ shutdownPromise ??= (async () => {+ // Reject new upgrades before the host's one-shot socket drain; a socket+ // admitted afterward would have no later mount shutdown to reap it.+ httpServer.off('upgrade', onUpgrade);+ await collaborationHost.shutdown();+ })();+ return shutdownPromise;+ };+return {- wss,- shutdown: async (): Promise<void> => {- if (shuttingDown) return;- // Set before destroying sockets so any `'close'` handler that fires as a- // result sees the flag and skips scheduling fresh grace-cleanup work.- shuttingDown = true;- // Destroy every live upgrade socket. Without this the caller's- // `wss.close()` and `httpServer.close()` steps block on the still-open- // sockets until their destroy-step timeout fires (see- // `MountMcpAndApiHandle.shutdown`). Destroying the raw socket also fires- // each WS's `'close'` handler, so keepalive cleanup still runs.- for (const socket of liveUpgradeSockets) {- try {- socket.destroy();- } catch {- // Best-effort — an already-destroyed socket is a no-op.- }- }- liveUpgradeSockets.clear();- for (const timer of keepaliveGraceTimers.values()) {- clearTimeout(timer);- }- keepaliveGraceTimers.clear();- if (keepaliveGraceInflight.size > 0) {- await Promise.allSettled(keepaliveGraceInflight);- }- },+ wss: collaborationHost.wss,+ shutdown,};}@@ -777,62 +475,4 @@ export function mountMcpAndApi(opts: MountMcpAndApiOptions): MountMcpAndApiHandl** Exported for unit testing. Never throws.*/-export function parseKeepaliveConnectionId(url: string | undefined): string | null {- if (!url) return null;- try {- // The second arg is a dummy base so `new URL` accepts path-only inputs.- const parsed = new URL(url, 'http://localhost');- const connectionId = parsed.searchParams.get('connectionId');- return validateAgentId(connectionId);- } catch {- return null;- }-}--/**- * Identity bundle parsed from the keepalive URL when the cli's MCP shim- * passes `displayName` + `clientName` + `colorSeed` alongside `connectionId`.- * All three must be present for the server's WS-upgrade handler to bootstrap- * a presence entry — the entry shape requires `displayName` + `icon` (derived- * from `clientName`) + `color` (derived from `colorSeed`), and a partial- * identity has no useful fallback.- *- * Length cap mirrors `validateAgentId` defense-in-depth: log-injection +- * bounded-cardinality span attribute hygiene. 256 chars is generous for- * human display names and conservatively below the URL line-length some- * proxies start truncating at.- *- * Exported for unit testing. Never throws.- */-const MAX_KEEPALIVE_IDENTITY_LEN = 256;--function sanitizeIdentityField(raw: string | null): string | null {- if (raw === null) return null;- if (raw.length === 0 || raw.length > MAX_KEEPALIVE_IDENTITY_LEN) return null;- // Strip control chars (defense-in-depth against log-injection / awareness- // value pollution). Allow normal printable Unicode (display names may- // include spaces, punctuation, non-ASCII letters).- // biome-ignore lint/suspicious/noControlCharactersInRegex: intentional sanitisation- if (/[ -]/.test(raw)) return null;- return raw;-}--interface KeepaliveIdentity {- displayName: string;- clientName: string;- colorSeed: string;-}--export function parseKeepaliveIdentity(url: string | undefined): KeepaliveIdentity | null {- if (!url) return null;- try {- const parsed = new URL(url, 'http://localhost');- const displayName = sanitizeIdentityField(parsed.searchParams.get('displayName'));- const clientName = sanitizeIdentityField(parsed.searchParams.get('clientName'));- const colorSeed = sanitizeIdentityField(parsed.searchParams.get('colorSeed'));- if (displayName === null || clientName === null || colorSeed === null) return null;- return { displayName, clientName, colorSeed };- } catch {- return null;- }-}+export { parseKeepaliveConnectionId, parseKeepaliveIdentity } from './collaboration-host.ts';