@intent-systems/nexus 2026.1.5-3

package/dist/gateway/server-chat.js

@@ -0,0 +1,159 @@
+import { formatForLog } from "./ws-log.js";
+export function createChatRunRegistry() {
+    const chatRunSessions = new Map();
+    const add = (sessionId, entry) => {
+        const queue = chatRunSessions.get(sessionId);
+        if (queue) {
+            queue.push(entry);
+        }
+        else {
+            chatRunSessions.set(sessionId, [entry]);
+        }
+    };
+    const peek = (sessionId) => chatRunSessions.get(sessionId)?.[0];
+    const shift = (sessionId) => {
+        const queue = chatRunSessions.get(sessionId);
+        if (!queue || queue.length === 0)
+            return undefined;
+        const entry = queue.shift();
+        if (!queue.length)
+            chatRunSessions.delete(sessionId);
+        return entry;
+    };
+    const remove = (sessionId, clientRunId, sessionKey) => {
+        const queue = chatRunSessions.get(sessionId);
+        if (!queue || queue.length === 0)
+            return undefined;
+        const idx = queue.findIndex((entry) => entry.clientRunId === clientRunId &&
+            (sessionKey ? entry.sessionKey === sessionKey : true));
+        if (idx < 0)
+            return undefined;
+        const [entry] = queue.splice(idx, 1);
+        if (!queue.length)
+            chatRunSessions.delete(sessionId);
+        return entry;
+    };
+    const clear = () => {
+        chatRunSessions.clear();
+    };
+    return { add, peek, shift, remove, clear };
+}
+export function createChatRunState() {
+    const registry = createChatRunRegistry();
+    const buffers = new Map();
+    const deltaSentAt = new Map();
+    const clear = () => {
+        registry.clear();
+        buffers.clear();
+        deltaSentAt.clear();
+    };
+    return {
+        registry,
+        buffers,
+        deltaSentAt,
+        clear,
+    };
+}
+export function createAgentEventHandler({ broadcast, bridgeSendToSession, agentRunSeq, chatRunState, resolveSessionKeyForRun, clearAgentRunContext, }) {
+    const emitChatDelta = (sessionKey, clientRunId, seq, text) => {
+        chatRunState.buffers.set(clientRunId, text);
+        const now = Date.now();
+        const last = chatRunState.deltaSentAt.get(clientRunId) ?? 0;
+        if (now - last < 150)
+            return;
+        chatRunState.deltaSentAt.set(clientRunId, now);
+        const payload = {
+            runId: clientRunId,
+            sessionKey,
+            seq,
+            state: "delta",
+            message: {
+                role: "assistant",
+                content: [{ type: "text", text }],
+                timestamp: now,
+            },
+        };
+        broadcast("chat", payload, { dropIfSlow: true });
+        bridgeSendToSession(sessionKey, "chat", payload);
+    };
+    const emitChatFinal = (sessionKey, clientRunId, seq, jobState, error) => {
+        const text = chatRunState.buffers.get(clientRunId)?.trim() ?? "";
+        chatRunState.buffers.delete(clientRunId);
+        chatRunState.deltaSentAt.delete(clientRunId);
+        if (jobState === "done") {
+            const payload = {
+                runId: clientRunId,
+                sessionKey,
+                seq,
+                state: "final",
+                message: text
+                    ? {
+                        role: "assistant",
+                        content: [{ type: "text", text }],
+                        timestamp: Date.now(),
+                    }
+                    : undefined,
+            };
+            broadcast("chat", payload);
+            bridgeSendToSession(sessionKey, "chat", payload);
+            return;
+        }
+        const payload = {
+            runId: clientRunId,
+            sessionKey,
+            seq,
+            state: "error",
+            errorMessage: error ? formatForLog(error) : undefined,
+        };
+        broadcast("chat", payload);
+        bridgeSendToSession(sessionKey, "chat", payload);
+    };
+    return (evt) => {
+        const chatLink = chatRunState.registry.peek(evt.runId);
+        const sessionKey = chatLink?.sessionKey ?? resolveSessionKeyForRun(evt.runId);
+        // Include sessionKey so Control UI can filter tool streams per session.
+        const agentPayload = sessionKey ? { ...evt, sessionKey } : evt;
+        const last = agentRunSeq.get(evt.runId) ?? 0;
+        if (evt.seq !== last + 1) {
+            broadcast("agent", {
+                runId: evt.runId,
+                stream: "error",
+                ts: Date.now(),
+                sessionKey,
+                data: {
+                    reason: "seq gap",
+                    expected: last + 1,
+                    received: evt.seq,
+                },
+            });
+        }
+        agentRunSeq.set(evt.runId, evt.seq);
+        broadcast("agent", agentPayload);
+        const lifecyclePhase = evt.stream === "lifecycle" && typeof evt.data?.phase === "string"
+            ? evt.data.phase
+            : null;
+        if (sessionKey) {
+            bridgeSendToSession(sessionKey, "agent", agentPayload);
+            if (evt.stream === "assistant" && typeof evt.data?.text === "string") {
+                const clientRunId = chatLink?.clientRunId ?? evt.runId;
+                emitChatDelta(sessionKey, clientRunId, evt.seq, evt.data.text);
+            }
+            else if (lifecyclePhase === "end" || lifecyclePhase === "error") {
+                if (chatLink) {
+                    const finished = chatRunState.registry.shift(evt.runId);
+                    if (!finished) {
+                        clearAgentRunContext(evt.runId);
+                        return;
+                    }
+                    emitChatFinal(finished.sessionKey, finished.clientRunId, evt.seq, lifecyclePhase === "error" ? "error" : "done", evt.data?.error);
+                }
+                else {
+                    emitChatFinal(sessionKey, evt.runId, evt.seq, lifecyclePhase === "error" ? "error" : "done", evt.data?.error);
+                }
+            }
+        }
+        if (lifecyclePhase === "end" || lifecyclePhase === "error") {
+            clearAgentRunContext(evt.runId);
+        }
+    };
+}

package/dist/gateway/server-constants.js

@@ -0,0 +1,8 @@
+export const MAX_PAYLOAD_BYTES = 512 * 1024; // cap incoming frame size
+export const MAX_BUFFERED_BYTES = 1.5 * 1024 * 1024; // per-connection send buffer limit
+export const MAX_CHAT_HISTORY_MESSAGES_BYTES = 6 * 1024 * 1024; // keep history responses comfortably under client WS limits
+export const HANDSHAKE_TIMEOUT_MS = 10_000;
+export const TICK_INTERVAL_MS = 30_000;
+export const HEALTH_REFRESH_INTERVAL_MS = 60_000;
+export const DEDUPE_TTL_MS = 5 * 60_000;
+export const DEDUPE_MAX = 1000;

package/dist/gateway/server-discovery.js

@@ -0,0 +1,62 @@
+import fs from "node:fs";
+import path from "node:path";
+import { getTailnetHostname } from "../infra/tailscale.js";
+import { runExec } from "../process/exec.js";
+export function formatBonjourInstanceName(displayName) {
+    const trimmed = displayName.trim();
+    if (!trimmed)
+        return "Nexus";
+    if (/nexus/i.test(trimmed))
+        return trimmed;
+    return `${trimmed} (Nexus)`;
+}
+export function resolveBonjourCliPath(opts = {}) {
+    const env = opts.env ?? process.env;
+    const envPath = env.NEXUS_CLI_PATH?.trim();
+    if (envPath)
+        return envPath;
+    const statSync = opts.statSync ?? fs.statSync;
+    const isFile = (candidate) => {
+        try {
+            return statSync(candidate).isFile();
+        }
+        catch {
+            return false;
+        }
+    };
+    const execPath = opts.execPath ?? process.execPath;
+    const execDir = path.dirname(execPath);
+    const siblingCli = path.join(execDir, "nexus");
+    if (isFile(siblingCli))
+        return siblingCli;
+    const argv = opts.argv ?? process.argv;
+    const argvPath = argv[1];
+    if (argvPath && isFile(argvPath)) {
+        const base = path.basename(argvPath);
+        if (!base.includes("gateway-daemon"))
+            return argvPath;
+    }
+    const cwd = opts.cwd ?? process.cwd();
+    const distCli = path.join(cwd, "dist", "index.js");
+    if (isFile(distCli))
+        return distCli;
+    const binCli = path.join(cwd, "bin", "nexus.js");
+    if (isFile(binCli))
+        return binCli;
+    return undefined;
+}
+export async function resolveTailnetDnsHint(opts) {
+    const env = opts?.env ?? process.env;
+    const envRaw = env.NEXUS_TAILNET_DNS?.trim();
+    const envValue = envRaw && envRaw.length > 0 ? envRaw.replace(/\.$/, "") : "";
+    if (envValue)
+        return envValue;
+    const exec = opts?.exec ??
+        ((command, args) => runExec(command, args, { timeoutMs: 1500, maxBuffer: 200_000 }));
+    try {
+        return await getTailnetHostname(exec);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/gateway/server-http.js

@@ -0,0 +1,165 @@
+import { createServer as createHttpServer, } from "node:http";
+import { handleA2uiHttpRequest } from "../canvas-host/a2ui.js";
+import { handleControlUiHttpRequest } from "./control-ui.js";
+import { extractHookToken, normalizeAgentPayload, normalizeHookHeaders, normalizeWakePayload, readJsonBody, } from "./hooks.js";
+import { applyHookMappings } from "./hooks-mapping.js";
+function sendJson(res, status, body) {
+    res.statusCode = status;
+    res.setHeader("Content-Type", "application/json; charset=utf-8");
+    res.end(JSON.stringify(body));
+}
+export function createHooksRequestHandler(opts) {
+    const { getHooksConfig, bindHost, port, logHooks, dispatchAgentHook, dispatchWakeHook, } = opts;
+    return async (req, res) => {
+        const hooksConfig = getHooksConfig();
+        if (!hooksConfig)
+            return false;
+        const url = new URL(req.url ?? "/", `http://${bindHost}:${port}`);
+        const basePath = hooksConfig.basePath;
+        if (url.pathname !== basePath && !url.pathname.startsWith(`${basePath}/`)) {
+            return false;
+        }
+        const token = extractHookToken(req, url);
+        if (!token || token !== hooksConfig.token) {
+            res.statusCode = 401;
+            res.setHeader("Content-Type", "text/plain; charset=utf-8");
+            res.end("Unauthorized");
+            return true;
+        }
+        if (req.method !== "POST") {
+            res.statusCode = 405;
+            res.setHeader("Allow", "POST");
+            res.setHeader("Content-Type", "text/plain; charset=utf-8");
+            res.end("Method Not Allowed");
+            return true;
+        }
+        const subPath = url.pathname.slice(basePath.length).replace(/^\/+/, "");
+        if (!subPath) {
+            res.statusCode = 404;
+            res.setHeader("Content-Type", "text/plain; charset=utf-8");
+            res.end("Not Found");
+            return true;
+        }
+        const body = await readJsonBody(req, hooksConfig.maxBodyBytes);
+        if (!body.ok) {
+            const status = body.error === "payload too large" ? 413 : 400;
+            sendJson(res, status, { ok: false, error: body.error });
+            return true;
+        }
+        const payload = typeof body.value === "object" && body.value !== null ? body.value : {};
+        const headers = normalizeHookHeaders(req);
+        if (subPath === "wake") {
+            const normalized = normalizeWakePayload(payload);
+            if (!normalized.ok) {
+                sendJson(res, 400, { ok: false, error: normalized.error });
+                return true;
+            }
+            dispatchWakeHook(normalized.value);
+            sendJson(res, 200, { ok: true, mode: normalized.value.mode });
+            return true;
+        }
+        if (subPath === "agent") {
+            const normalized = normalizeAgentPayload(payload);
+            if (!normalized.ok) {
+                sendJson(res, 400, { ok: false, error: normalized.error });
+                return true;
+            }
+            const runId = dispatchAgentHook(normalized.value);
+            sendJson(res, 202, { ok: true, runId });
+            return true;
+        }
+        if (hooksConfig.mappings.length > 0) {
+            try {
+                const mapped = await applyHookMappings(hooksConfig.mappings, {
+                    payload: payload,
+                    headers,
+                    url,
+                    path: subPath,
+                });
+                if (mapped) {
+                    if (!mapped.ok) {
+                        sendJson(res, 400, { ok: false, error: mapped.error });
+                        return true;
+                    }
+                    if (mapped.action === null) {
+                        res.statusCode = 204;
+                        res.end();
+                        return true;
+                    }
+                    if (mapped.action.kind === "wake") {
+                        dispatchWakeHook({
+                            text: mapped.action.text,
+                            mode: mapped.action.mode,
+                        });
+                        sendJson(res, 200, { ok: true, mode: mapped.action.mode });
+                        return true;
+                    }
+                    const runId = dispatchAgentHook({
+                        message: mapped.action.message,
+                        name: mapped.action.name ?? "Hook",
+                        wakeMode: mapped.action.wakeMode,
+                        sessionKey: mapped.action.sessionKey ?? "",
+                        deliver: mapped.action.deliver === true,
+                        provider: mapped.action.provider ?? "last",
+                        to: mapped.action.to,
+                        thinking: mapped.action.thinking,
+                        timeoutSeconds: mapped.action.timeoutSeconds,
+                    });
+                    sendJson(res, 202, { ok: true, runId });
+                    return true;
+                }
+            }
+            catch (err) {
+                logHooks.warn(`hook mapping failed: ${String(err)}`);
+                sendJson(res, 500, { ok: false, error: "hook mapping failed" });
+                return true;
+            }
+        }
+        res.statusCode = 404;
+        res.setHeader("Content-Type", "text/plain; charset=utf-8");
+        res.end("Not Found");
+        return true;
+    };
+}
+export function createGatewayHttpServer(opts) {
+    const { canvasHost, controlUiEnabled, controlUiBasePath, handleHooksRequest, } = opts;
+    const httpServer = createHttpServer((req, res) => {
+        // Don't interfere with WebSocket upgrades; ws handles the 'upgrade' event.
+        if (String(req.headers.upgrade ?? "").toLowerCase() === "websocket")
+            return;
+        void (async () => {
+            if (await handleHooksRequest(req, res))
+                return;
+            if (canvasHost) {
+                if (await handleA2uiHttpRequest(req, res))
+                    return;
+                if (await canvasHost.handleHttpRequest(req, res))
+                    return;
+            }
+            if (controlUiEnabled) {
+                if (handleControlUiHttpRequest(req, res, {
+                    basePath: controlUiBasePath,
+                }))
+                    return;
+            }
+            res.statusCode = 404;
+            res.setHeader("Content-Type", "text/plain; charset=utf-8");
+            res.end("Not Found");
+        })().catch((err) => {
+            res.statusCode = 500;
+            res.setHeader("Content-Type", "text/plain; charset=utf-8");
+            res.end(String(err));
+        });
+    });
+    return httpServer;
+}
+export function attachGatewayUpgradeHandler(opts) {
+    const { httpServer, wss, canvasHost } = opts;
+    httpServer.on("upgrade", (req, socket, head) => {
+        if (canvasHost?.handleUpgrade(req, socket, head))
+            return;
+        wss.handleUpgrade(req, socket, head, (ws) => {
+            wss.emit("connection", ws, req);
+        });
+    });
+}

package/dist/gateway/server-methods/agent-job.js

@@ -0,0 +1,114 @@
+import { onAgentEvent } from "../../infra/agent-events.js";
+const AGENT_RUN_CACHE_TTL_MS = 10 * 60_000;
+const agentRunCache = new Map();
+const agentRunStarts = new Map();
+let agentRunListenerStarted = false;
+function pruneAgentRunCache(now = Date.now()) {
+    for (const [runId, entry] of agentRunCache) {
+        if (now - entry.ts > AGENT_RUN_CACHE_TTL_MS) {
+            agentRunCache.delete(runId);
+        }
+    }
+}
+function recordAgentRunSnapshot(entry) {
+    pruneAgentRunCache(entry.ts);
+    agentRunCache.set(entry.runId, entry);
+}
+function ensureAgentRunListener() {
+    if (agentRunListenerStarted)
+        return;
+    agentRunListenerStarted = true;
+    onAgentEvent((evt) => {
+        if (!evt)
+            return;
+        if (evt.stream !== "lifecycle")
+            return;
+        const phase = evt.data?.phase;
+        if (phase === "start") {
+            const startedAt = typeof evt.data?.startedAt === "number"
+                ? evt.data.startedAt
+                : undefined;
+            agentRunStarts.set(evt.runId, startedAt ?? Date.now());
+            return;
+        }
+        if (phase !== "end" && phase !== "error")
+            return;
+        const startedAt = typeof evt.data?.startedAt === "number"
+            ? evt.data.startedAt
+            : agentRunStarts.get(evt.runId);
+        const endedAt = typeof evt.data?.endedAt === "number"
+            ? evt.data.endedAt
+            : undefined;
+        const error = typeof evt.data?.error === "string"
+            ? evt.data.error
+            : undefined;
+        agentRunStarts.delete(evt.runId);
+        recordAgentRunSnapshot({
+            runId: evt.runId,
+            status: phase === "error" ? "error" : "ok",
+            startedAt,
+            endedAt,
+            error,
+            ts: Date.now(),
+        });
+    });
+}
+function getCachedAgentRun(runId) {
+    pruneAgentRunCache();
+    return agentRunCache.get(runId);
+}
+export async function waitForAgentJob(params) {
+    const { runId, timeoutMs } = params;
+    ensureAgentRunListener();
+    const cached = getCachedAgentRun(runId);
+    if (cached)
+        return cached;
+    if (timeoutMs <= 0)
+        return null;
+    return await new Promise((resolve) => {
+        let settled = false;
+        const finish = (entry) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            unsubscribe();
+            resolve(entry);
+        };
+        const unsubscribe = onAgentEvent((evt) => {
+            if (!evt || evt.stream !== "lifecycle")
+                return;
+            if (evt.runId !== runId)
+                return;
+            const phase = evt.data?.phase;
+            if (phase !== "end" && phase !== "error")
+                return;
+            const cached = getCachedAgentRun(runId);
+            if (cached) {
+                finish(cached);
+                return;
+            }
+            const startedAt = typeof evt.data?.startedAt === "number"
+                ? evt.data.startedAt
+                : agentRunStarts.get(evt.runId);
+            const endedAt = typeof evt.data?.endedAt === "number"
+                ? evt.data.endedAt
+                : undefined;
+            const error = typeof evt.data?.error === "string"
+                ? evt.data.error
+                : undefined;
+            const snapshot = {
+                runId: evt.runId,
+                status: phase === "error" ? "error" : "ok",
+                startedAt,
+                endedAt,
+                error,
+                ts: Date.now(),
+            };
+            recordAgentRunSnapshot(snapshot);
+            finish(snapshot);
+        });
+        const timer = setTimeout(() => finish(null), Math.max(1, timeoutMs));
+    });
+}
+ensureAgentRunListener();