auvrynt 1.0.2 → 1.0.5

package/dist/infrastructure/http-rate-limit.js

@@ -0,0 +1,42 @@
+import { requestIp } from "../logger.js";
+/** Small in-memory limiter for Auvrynt's single-process OAuth endpoints. */
+export function createFixedWindowRateLimiter(options) {
+    const maxClients = options.maxClients ?? 10_000;
+    const buckets = new Map();
+    let requestCounter = 0;
+    const prune = (now) => {
+        for (const [key, bucket] of buckets) {
+            if (bucket.resetAt <= now)
+                buckets.delete(key);
+        }
+        while (buckets.size >= maxClients) {
+            const oldestKey = buckets.keys().next().value;
+            if (!oldestKey)
+                break;
+            buckets.delete(oldestKey);
+        }
+    };
+    return (req, res, next) => {
+        const now = Date.now();
+        requestCounter++;
+        if (requestCounter % 100 === 0 || buckets.size >= maxClients)
+            prune(now);
+        const key = requestIp(req) ?? "unknown";
+        let bucket = buckets.get(key);
+        if (!bucket || bucket.resetAt <= now) {
+            if (buckets.size >= maxClients)
+                prune(now);
+            bucket = { count: 0, resetAt: now + options.windowMs };
+            buckets.set(key, bucket);
+        }
+        if (bucket.count >= options.maxRequests) {
+            const retryAfterSeconds = Math.max(1, Math.ceil((bucket.resetAt - now) / 1_000));
+            res.setHeader("Cache-Control", "no-store");
+            res.setHeader("Retry-After", String(retryAfterSeconds));
+            res.status(429).json({ error: options.message ?? "Too many requests. Try again later." });
+            return;
+        }
+        bucket.count++;
+        next();
+    };
+}

package/dist/infrastructure/http-server-hardening.js

@@ -0,0 +1,23 @@
+export const HTTP_REQUEST_TIMEOUT_MS = 5 * 60_000;
+export const HTTP_HEADERS_TIMEOUT_MS = 30_000;
+export const HTTP_KEEP_ALIVE_TIMEOUT_MS = 75_000;
+export const HTTP_SOCKET_KEEP_ALIVE_DELAY_MS = 30_000;
+export const HTTP_MAX_HEADERS_COUNT = 100;
+export const HTTP_MAX_REQUESTS_PER_SOCKET = 10_000;
+/**
+ * MCP responses may stream for a long time, but receiving request headers and
+ * bodies must still have finite bounds to resist slow-client DoS.
+ */
+export function hardenHttpServer(httpServer) {
+    httpServer.requestTimeout = HTTP_REQUEST_TIMEOUT_MS;
+    httpServer.headersTimeout = HTTP_HEADERS_TIMEOUT_MS;
+    httpServer.keepAliveTimeout = HTTP_KEEP_ALIVE_TIMEOUT_MS;
+    httpServer.timeout = 0;
+    httpServer.maxHeadersCount = HTTP_MAX_HEADERS_COUNT;
+    httpServer.maxRequestsPerSocket = HTTP_MAX_REQUESTS_PER_SOCKET;
+    httpServer.on("connection", configureHttpSocket);
+}
+export function configureHttpSocket(socket) {
+    socket.setKeepAlive(true, HTTP_SOCKET_KEEP_ALIVE_DELAY_MS);
+    socket.setNoDelay(true);
+}

package/dist/infrastructure/integration-queue.js

@@ -0,0 +1,46 @@
+const queues = new Map();
+export const MAX_INTEGRATION_QUEUE_DEPTH = 16;
+export function enqueueIntegration(integration, fn) {
+    const state = queues.get(integration) ?? {
+        tail: Promise.resolve(),
+        pending: 0,
+        active: false,
+    };
+    const depth = state.pending + (state.active ? 1 : 0);
+    if (depth >= MAX_INTEGRATION_QUEUE_DEPTH) {
+        throw new Error(`${integration} integration queue is full (max ${MAX_INTEGRATION_QUEUE_DEPTH}). Wait for the active operation before retrying.`);
+    }
+    state.pending += 1;
+    queues.set(integration, state);
+    const previous = state.tail.catch(() => undefined);
+    let release;
+    state.tail = new Promise((resolve) => { release = resolve; });
+    return previous.then(async () => {
+        state.pending -= 1;
+        state.active = true;
+        try {
+            return await fn();
+        }
+        finally {
+            state.active = false;
+            release();
+            if (state.pending === 0 && queues.get(integration) === state) {
+                queues.delete(integration);
+            }
+        }
+    });
+}
+export function getQueueDiagnostics() {
+    const result = {};
+    for (const [integration, state] of queues) {
+        result[integration] = { active: state.active, pending: state.pending };
+    }
+    return result;
+}
+export function clearIntegrationQueue(integration) {
+    const state = queues.get(integration);
+    if (state?.active || (state?.pending ?? 0) > 0) {
+        throw new Error(`Cannot clear active integration queue: ${integration}`);
+    }
+    queues.delete(integration);
+}

package/dist/infrastructure/logger.js

@@ -0,0 +1,129 @@
+const MAX_RECENT_LOG_ENTRIES = 500;
+const recentEntries = [];
+let nextRecentLogId = 1;
+const LEVEL_WEIGHT = {
+    silent: 0,
+    error: 1,
+    warn: 2,
+    info: 3,
+    debug: 4,
+};
+export function shouldLog(config, level) {
+    return LEVEL_WEIGHT[config.level] >= LEVEL_WEIGHT[level];
+}
+export function logEvent(config, level, event, fields = {}) {
+    if (!shouldLog(config, level))
+        return;
+    const ts = new Date().toISOString();
+    const safeFields = sanitizeLogFields(fields);
+    recentEntries.push({ id: nextRecentLogId++, ts, level, event, fields: safeFields });
+    if (recentEntries.length > MAX_RECENT_LOG_ENTRIES) {
+        recentEntries.splice(0, recentEntries.length - MAX_RECENT_LOG_ENTRIES);
+    }
+    if (process.env.AUVRYNT_START_MODE === "true") {
+        const emitter = global.auvryntLogEmitter;
+        if (typeof emitter === "function") {
+            emitter(level, event, safeFields);
+        }
+        return;
+    }
+    const entry = {
+        ts,
+        level,
+        event,
+        ...safeFields,
+    };
+    const line = config.format === "pretty" ? formatPretty(entry) : JSON.stringify(entry);
+    if (level === "error") {
+        console.error(line);
+    }
+    else if (level === "warn") {
+        console.warn(line);
+    }
+    else {
+        console.log(line);
+    }
+}
+export function recentLogEntries(limit = 200) {
+    const boundedLimit = Number.isInteger(limit)
+        ? Math.max(1, Math.min(limit, MAX_RECENT_LOG_ENTRIES))
+        : 200;
+    return recentEntries.slice(-boundedLimit).map((entry) => ({
+        ...entry,
+        fields: { ...entry.fields },
+    }));
+}
+export function requestIp(req) {
+    // Express has already applied the server's trusted-proxy policy to req.ip.
+    // Reading forwarding headers directly here would let callers spoof log identities.
+    return req.ip ?? req.socket.remoteAddress;
+}
+export function isLoopbackIp(value) {
+    if (!value)
+        return false;
+    const normalized = value.trim().toLowerCase();
+    return normalized === "127.0.0.1"
+        || normalized === "::1"
+        || normalized === "localhost"
+        || normalized.startsWith("127.")
+        || normalized.startsWith("::ffff:127.");
+}
+export function isLoopbackRequest(req) {
+    return isLoopbackIp(requestIp(req));
+}
+export function requestPath(req) {
+    return req.path || req.url.split("?")[0] || req.url;
+}
+export function sessionIdPrefix(sessionId) {
+    return sessionId ? sessionId.slice(0, 8) : undefined;
+}
+export function commandPreview(command) {
+    const normalized = command.replace(/\s+/g, " ").trim();
+    return normalized.length > 120 ? `${normalized.slice(0, 117)}...` : normalized;
+}
+function sanitizeLogFields(fields) {
+    return Object.fromEntries(Object.entries(fields).map(([key, value]) => [key, sanitizeLogValue(key, value)]));
+}
+function sanitizeLogValue(key, value) {
+    if (/authorization|token|secret|password|cookie/i.test(key))
+        return "[redacted]";
+    if (/(^|_)(ip|address)$/i.test(key) || /remote(address)?/i.test(key))
+        return "[network-address]";
+    if (typeof value === "string") {
+        const redacted = redactNetworkAddresses(value);
+        return redacted.length > 2_000 ? `${redacted.slice(0, 1_997)}...` : redacted;
+    }
+    if (Array.isArray(value)) {
+        return value.slice(0, 50).map((item) => sanitizeLogValue("item", item));
+    }
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value)
+            .slice(0, 50)
+            .map(([childKey, childValue]) => [
+            childKey,
+            sanitizeLogValue(childKey, childValue),
+        ]));
+    }
+    return value;
+}
+function redactNetworkAddresses(value) {
+    return value
+        .replace(/\b(?:\d{1,3}\.){3}\d{1,3}(?::\d+)?\b/g, "[network-address]")
+        .replace(/\[(?:[0-9a-f]*:){2,}[0-9a-f:]*\](?::\d+)?/gi, "[network-address]")
+        .replace(/\b::1\b/gi, "[network-address]");
+}
+function formatPretty(entry) {
+    const ts = String(entry.ts);
+    const level = String(entry.level).toUpperCase();
+    const event = String(entry.event);
+    const rest = Object.entries(entry)
+        .filter(([key, value]) => !["ts", "level", "event"].includes(key) && value !== undefined)
+        .map(([key, value]) => `${key}=${formatPrettyValue(value)}`)
+        .join(" ");
+    return rest ? `${ts} ${level} ${event} ${rest}` : `${ts} ${level} ${event}`;
+}
+function formatPrettyValue(value) {
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    return JSON.stringify(value);
+}

package/dist/infrastructure/mcp-event-store.js

@@ -0,0 +1,103 @@
+import { randomUUID } from "node:crypto";
+export const DEFAULT_MCP_EVENT_RETENTION_MS = 24 * 60 * 60 * 1000;
+export const DEFAULT_MCP_EVENT_LIMIT = 2_048;
+export const DEFAULT_MCP_EVENT_STORE_BYTES = 3 * 1024 * 1024;
+export const DEFAULT_MCP_SINGLE_EVENT_BYTES = 1024 * 1024;
+/**
+ * Per-session replay storage for MCP SSE reconnects. It is deliberately bounded
+ * by age and count so a long-running web-agent connection cannot grow memory
+ * without limit.
+ */
+export class BoundedMcpEventStore {
+    events = [];
+    eventsById = new Map();
+    maxEvents;
+    maxBytes;
+    maxEventBytes;
+    retentionMs;
+    now;
+    totalBytes = 0;
+    constructor(options = {}) {
+        this.maxEvents = positiveInteger(options.maxEvents, DEFAULT_MCP_EVENT_LIMIT);
+        this.maxBytes = positiveInteger(options.maxBytes, DEFAULT_MCP_EVENT_STORE_BYTES);
+        this.maxEventBytes = Math.min(positiveInteger(options.maxEventBytes, DEFAULT_MCP_SINGLE_EVENT_BYTES), this.maxBytes);
+        this.retentionMs = positiveInteger(options.retentionMs, DEFAULT_MCP_EVENT_RETENTION_MS);
+        this.now = options.now ?? Date.now;
+    }
+    async storeEvent(streamId, message) {
+        const storedAt = this.now();
+        this.prune(storedAt);
+        const eventId = `evt-${storedAt.toString(36)}-${randomUUID()}`;
+        const measuredBytes = serializedBytes(message);
+        const replayMessage = measuredBytes > this.maxEventBytes
+            ? replayTooLargeMessage(message, measuredBytes, this.maxEventBytes)
+            : message;
+        const bytes = serializedBytes(replayMessage);
+        const event = { eventId, streamId, message: replayMessage, storedAt, bytes };
+        this.events.push(event);
+        this.eventsById.set(eventId, event);
+        this.totalBytes += bytes;
+        this.prune(storedAt);
+        return eventId;
+    }
+    async getStreamIdForEventId(eventId) {
+        this.prune(this.now());
+        return this.eventsById.get(eventId)?.streamId;
+    }
+    async replayEventsAfter(lastEventId, options) {
+        this.prune(this.now());
+        const lastEvent = this.eventsById.get(lastEventId);
+        if (!lastEvent)
+            return "";
+        let found = false;
+        for (const event of this.events) {
+            if (event.streamId !== lastEvent.streamId)
+                continue;
+            if (event.eventId === lastEventId) {
+                found = true;
+                continue;
+            }
+            if (found)
+                await options.send(event.eventId, event.message);
+        }
+        return lastEvent.streamId;
+    }
+    size() {
+        this.prune(this.now());
+        return this.events.length;
+    }
+    byteSize() {
+        this.prune(this.now());
+        return this.totalBytes;
+    }
+    prune(now) {
+        const oldestAllowed = now - this.retentionMs;
+        while (this.events.length > 0
+            && (this.events[0].storedAt < oldestAllowed
+                || this.events.length > this.maxEvents
+                || this.totalBytes > this.maxBytes)) {
+            const removed = this.events.shift();
+            if (removed) {
+                this.eventsById.delete(removed.eventId);
+                this.totalBytes = Math.max(0, this.totalBytes - removed.bytes);
+            }
+        }
+    }
+}
+function positiveInteger(value, fallback) {
+    return Number.isInteger(value) && value > 0 ? value : fallback;
+}
+function serializedBytes(message) {
+    return Buffer.byteLength(JSON.stringify(message), "utf8");
+}
+function replayTooLargeMessage(message, actualBytes, limitBytes) {
+    const id = "id" in message ? message.id : null;
+    return {
+        jsonrpc: "2.0",
+        id,
+        error: {
+            code: -32002,
+            message: `The original ${actualBytes}-byte result exceeded the ${limitBytes}-byte replay limit. Retry with a narrower request.`,
+        },
+    };
+}

package/dist/infrastructure/ngrok-auth-pool.js

@@ -0,0 +1,208 @@
+import { createHash } from "node:crypto";
+import { loadAuvryntFiles, writeAuvryntAuth, writeAuvryntConfig, } from "./user-config.js";
+export const MAX_NGROK_AUTHTOKENS = 20;
+export function validateNgrokAuthtoken(value) {
+    if (typeof value !== "string")
+        throw new Error("Enter a valid ngrok authtoken.");
+    const token = value.trim();
+    if (token.length < 16 || token.length > 512) {
+        throw new Error("ngrok authtokens must be between 16 and 512 characters.");
+    }
+    if (/\s|[\u0000-\u001f\u007f]/u.test(token)) {
+        throw new Error("ngrok authtokens must not contain whitespace or control characters.");
+    }
+    return token;
+}
+export function ngrokAuthtokenFingerprint(token) {
+    return createHash("sha256").update(token).digest("hex").slice(0, 10).toUpperCase();
+}
+export function resolveNgrokAuthtoken(files = loadAuvryntFiles(), env = process.env) {
+    const override = env.AUVRYNT_NGROK_AUTHTOKEN?.trim();
+    if (override)
+        return override;
+    const pool = readPool(files, env);
+    return pool.activeIndex === null ? undefined : pool.tokens[pool.activeIndex];
+}
+export function getCurrentNgrokAuthtoken(files = loadAuvryntFiles(), env = process.env) {
+    return resolveNgrokAuthtoken(files, env);
+}
+export function summarizeNgrokAuthtokens(files = loadAuvryntFiles(), env = process.env) {
+    return summarizePool(readPool(files, env));
+}
+export function addNgrokAuthtoken(value, env = process.env) {
+    const token = validateNgrokAuthtoken(value);
+    const files = loadAuvryntFiles(env);
+    const pool = readPool(files, env);
+    if (pool.tokens.includes(token))
+        throw new Error("That ngrok authtoken is already saved.");
+    if (pool.tokens.length >= MAX_NGROK_AUTHTOKENS) {
+        throw new Error(`A maximum of ${MAX_NGROK_AUTHTOKENS} ngrok authtokens can be saved.`);
+    }
+    const previousActiveToken = activeToken(pool);
+    pool.tokens.push(token);
+    if (pool.activeIndex === null || activeTokenIsExhausted(pool)) {
+        pool.activeIndex = firstAvailableTokenIndex(pool) ?? pool.tokens.length - 1;
+    }
+    const activeChanged = previousActiveToken !== activeToken(pool);
+    persistPool(files, pool, env);
+    return { summary: summarizePool(pool), activeChanged };
+}
+export function removeNgrokAuthtoken(index, env = process.env) {
+    const files = loadAuvryntFiles(env);
+    const pool = readPool(files, env);
+    const tokenIndex = parseTokenIndex(index, pool.tokens.length);
+    const previousActive = pool.activeIndex;
+    const previousActiveToken = activeToken(pool);
+    const [removed] = pool.tokens.splice(tokenIndex, 1);
+    if (removed)
+        delete pool.quotaExhausted[ngrokAuthtokenFingerprint(removed)];
+    if (pool.tokens.length === 0) {
+        pool.activeIndex = null;
+    }
+    else if (previousActive === null) {
+        pool.activeIndex = 0;
+    }
+    else if (tokenIndex < previousActive) {
+        pool.activeIndex = previousActive - 1;
+    }
+    else if (tokenIndex === previousActive) {
+        pool.activeIndex = Math.min(tokenIndex, pool.tokens.length - 1);
+    }
+    if (activeTokenIsExhausted(pool)) {
+        pool.activeIndex = firstAvailableTokenIndex(pool) ?? pool.activeIndex;
+    }
+    const activeChanged = previousActiveToken !== activeToken(pool);
+    persistPool(files, pool, env);
+    return { summary: summarizePool(pool), activeChanged };
+}
+export function activateNgrokAuthtoken(index, env = process.env) {
+    if (env.AUVRYNT_NGROK_AUTHTOKEN?.trim()) {
+        throw new Error("AUVRYNT_NGROK_AUTHTOKEN is overriding the saved token pool. Remove that environment variable before switching tokens here.");
+    }
+    const files = loadAuvryntFiles(env);
+    const pool = readPool(files, env);
+    const tokenIndex = parseTokenIndex(index, pool.tokens.length);
+    const fingerprint = ngrokAuthtokenFingerprint(pool.tokens[tokenIndex]);
+    const activeChanged = pool.activeIndex !== tokenIndex || Boolean(pool.quotaExhausted[fingerprint]);
+    pool.activeIndex = tokenIndex;
+    delete pool.quotaExhausted[fingerprint];
+    persistPool(files, pool, env);
+    return { summary: summarizePool(pool), activeChanged };
+}
+export function markActiveNgrokAuthtokenQuotaExceeded(exhaustedAt = new Date().toISOString(), env = process.env) {
+    const files = loadAuvryntFiles(env);
+    const pool = readPool(files, env);
+    if (pool.environmentOverride) {
+        return {
+            environmentOverride: true,
+            summary: summarizePool(pool),
+        };
+    }
+    if (pool.activeIndex === null || pool.tokens.length === 0) {
+        return {
+            environmentOverride: false,
+            summary: summarizePool(pool),
+        };
+    }
+    const currentIndex = pool.activeIndex;
+    const currentToken = pool.tokens[currentIndex];
+    const currentFingerprint = ngrokAuthtokenFingerprint(currentToken);
+    pool.quotaExhausted[currentFingerprint] = exhaustedAt;
+    let nextIndex = null;
+    for (let offset = 1; offset < pool.tokens.length; offset++) {
+        const candidateIndex = (currentIndex + offset) % pool.tokens.length;
+        const candidateFingerprint = ngrokAuthtokenFingerprint(pool.tokens[candidateIndex]);
+        if (!pool.quotaExhausted[candidateFingerprint]) {
+            nextIndex = candidateIndex;
+            break;
+        }
+    }
+    if (nextIndex !== null)
+        pool.activeIndex = nextIndex;
+    persistPool(files, pool, env);
+    const summary = summarizePool(pool);
+    return {
+        environmentOverride: false,
+        current: summary.tokens.find((token) => token.fingerprint === currentFingerprint),
+        next: nextIndex === null ? undefined : summary.tokens.find((token) => token.index === nextIndex),
+        summary,
+    };
+}
+function readPool(files, env) {
+    const environmentOverride = Boolean(env.AUVRYNT_NGROK_AUTHTOKEN?.trim());
+    const saved = Array.isArray(files.auth.ngrokAuthtokens)
+        ? files.auth.ngrokAuthtokens.map((token) => token.trim()).filter(Boolean)
+        : [];
+    const legacy = files.config.ngrokAuthtoken?.trim();
+    const tokens = deduplicate(legacy ? [...saved, legacy] : saved);
+    const configuredIndex = files.auth.ngrokActiveAuthtokenIndex;
+    const activeIndex = tokens.length === 0
+        ? null
+        : Number.isInteger(configuredIndex) && configuredIndex >= 0 && configuredIndex < tokens.length
+            ? configuredIndex
+            : 0;
+    return {
+        tokens,
+        activeIndex,
+        quotaExhausted: { ...(files.auth.ngrokQuotaExhausted ?? {}) },
+        environmentOverride,
+    };
+}
+function persistPool(files, pool, env) {
+    const validFingerprints = new Set(pool.tokens.map(ngrokAuthtokenFingerprint));
+    const quotaExhausted = Object.fromEntries(Object.entries(pool.quotaExhausted).filter(([fingerprint]) => validFingerprints.has(fingerprint)));
+    const nextAuth = {
+        ...files.auth,
+        ngrokAuthtokens: pool.tokens,
+        ngrokQuotaExhausted: quotaExhausted,
+    };
+    if (pool.activeIndex === null)
+        delete nextAuth.ngrokActiveAuthtokenIndex;
+    else
+        nextAuth.ngrokActiveAuthtokenIndex = pool.activeIndex;
+    writeAuvryntAuth(nextAuth, env);
+    if (files.config.ngrokAuthtoken !== undefined) {
+        const nextConfig = { ...files.config };
+        delete nextConfig.ngrokAuthtoken;
+        writeAuvryntConfig(nextConfig, env);
+    }
+}
+function summarizePool(pool) {
+    return {
+        enabled: pool.tokens.length > 0,
+        environmentOverride: pool.environmentOverride,
+        activeIndex: pool.environmentOverride ? null : pool.activeIndex,
+        tokens: pool.tokens.map((token, index) => {
+            const fingerprint = ngrokAuthtokenFingerprint(token);
+            return {
+                index,
+                fingerprint,
+                active: !pool.environmentOverride && index === pool.activeIndex,
+                ...(pool.quotaExhausted[fingerprint]
+                    ? { quotaExhaustedAt: pool.quotaExhausted[fingerprint] }
+                    : {}),
+            };
+        }),
+    };
+}
+function activeToken(pool) {
+    return pool.activeIndex === null ? undefined : pool.tokens[pool.activeIndex];
+}
+function activeTokenIsExhausted(pool) {
+    const token = activeToken(pool);
+    return Boolean(token && pool.quotaExhausted[ngrokAuthtokenFingerprint(token)]);
+}
+function firstAvailableTokenIndex(pool) {
+    const index = pool.tokens.findIndex((token) => !pool.quotaExhausted[ngrokAuthtokenFingerprint(token)]);
+    return index >= 0 ? index : null;
+}
+function parseTokenIndex(value, length) {
+    const index = Number(value);
+    if (!Number.isInteger(index) || index < 0 || index >= length) {
+        throw new Error("Select a valid saved ngrok token.");
+    }
+    return index;
+}
+function deduplicate(tokens) {
+    return Array.from(new Set(tokens));
+}

package/dist/infrastructure/request-context.js

@@ -0,0 +1,14 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+const als = new AsyncLocalStorage();
+export function runWithContext(ctx, fn) {
+    return als.run(ctx, fn);
+}
+export function getRequestContext() {
+    return als.getStore();
+}
+export function requireRequestContext() {
+    const ctx = als.getStore();
+    if (!ctx)
+        throw new Error("No request context available");
+    return ctx;
+}

package/dist/infrastructure/shutdown.js

@@ -0,0 +1,37 @@
+import { disconnectAllGodotEditorBridges } from "../godot-editor-bridge.js";
+import { clearBlenderClients } from "../blender-client.js";
+import { logEvent } from "../logger.js";
+export function createShutdownCoordinator(config, sessionRegistry, processManager, serenaManager, workspaceStore) {
+    let phase = "none";
+    let shutdownPromise;
+    return {
+        get phase() {
+            return phase;
+        },
+        shutdown() {
+            if (shutdownPromise)
+                return shutdownPromise;
+            shutdownPromise = (async () => {
+                const log = (msg, p) => {
+                    phase = p;
+                    logEvent(config.logging, "info", "shutdown", { phase: p, message: msg });
+                };
+                log("Closing MCP sessions...", "sessions_closed");
+                await sessionRegistry.closeAll("server_shutdown");
+                sessionRegistry.close();
+                log("Terminating processes...", "processes_terminated");
+                await Promise.allSettled([
+                    serenaManager.stopAllSessions(),
+                    processManager.stopAllProcesses(),
+                ]);
+                log("Disconnecting integrations...", "integrations_disconnected");
+                disconnectAllGodotEditorBridges();
+                clearBlenderClients();
+                log("Closing database...", "database_closed");
+                workspaceStore.close?.();
+                log("Shutdown complete", "database_closed");
+            })();
+            return shutdownPromise;
+        },
+    };
+}

package/dist/infrastructure/sse-heartbeat.js

@@ -0,0 +1,47 @@
+export const DEFAULT_SSE_HEARTBEAT_INTERVAL_MS = 15_000;
+/**
+ * Keeps long-running MCP SSE responses active through reverse proxies and
+ * tunnels. SSE comment frames are ignored by clients but count as traffic, so
+ * an otherwise silent build or render is less likely to be terminated as an
+ * upstream 502/504 timeout.
+ */
+export function attachSseHeartbeat(response, intervalMs = DEFAULT_SSE_HEARTBEAT_INTERVAL_MS) {
+    if (!Number.isFinite(intervalMs) || intervalMs < 1) {
+        throw new Error("SSE heartbeat interval must be a positive number.");
+    }
+    if (!response.headersSent) {
+        response.setHeader("Cache-Control", "no-cache, no-transform");
+        response.setHeader("X-Accel-Buffering", "no");
+    }
+    let stopped = false;
+    const stop = () => {
+        if (stopped)
+            return;
+        stopped = true;
+        clearInterval(timer);
+    };
+    const timer = setInterval(() => {
+        if (response.writableEnded || response.destroyed) {
+            stop();
+            return;
+        }
+        if (!response.headersSent || !isEventStream(response.getHeader("content-type")))
+            return;
+        try {
+            response.write(`: auvrynt-heartbeat ${Date.now()}\n\n`);
+        }
+        catch {
+            stop();
+        }
+    }, intervalMs);
+    timer.unref();
+    response.once("finish", stop);
+    response.once("close", stop);
+    return { stop };
+}
+function isEventStream(contentType) {
+    if (Array.isArray(contentType)) {
+        return contentType.some((value) => String(value).toLowerCase().includes("text/event-stream"));
+    }
+    return String(contentType ?? "").toLowerCase().includes("text/event-stream");
+}