@intent-systems/nexus 2026.1.5-3

package/dist/config/legacy.js

@@ -0,0 +1,425 @@
+const LEGACY_CONFIG_RULES = [
+    {
+        path: ["routing", "allowFrom"],
+        message: "routing.allowFrom was removed; use whatsapp.allowFrom instead (run `nexus doctor` to migrate).",
+    },
+    {
+        path: ["routing", "groupChat", "requireMention"],
+        message: 'routing.groupChat.requireMention was removed; use whatsapp/telegram/imessage groups defaults (e.g. whatsapp.groups."*".requireMention) instead (run `nexus doctor` to migrate).',
+    },
+    {
+        path: ["telegram", "requireMention"],
+        message: 'telegram.requireMention was removed; use telegram.groups."*".requireMention instead (run `nexus doctor` to migrate).',
+    },
+    {
+        path: ["agent", "model"],
+        message: "agent.model string was replaced by agent.model.primary/fallbacks and agent.models (run `nexus doctor` to migrate).",
+        match: (value) => typeof value === "string",
+    },
+    {
+        path: ["agent", "imageModel"],
+        message: "agent.imageModel string was replaced by agent.imageModel.primary/fallbacks (run `nexus doctor` to migrate).",
+        match: (value) => typeof value === "string",
+    },
+    {
+        path: ["agent", "allowedModels"],
+        message: "agent.allowedModels was replaced by agent.models (run `nexus doctor` to migrate).",
+    },
+    {
+        path: ["agent", "modelAliases"],
+        message: "agent.modelAliases was replaced by agent.models.*.alias (run `nexus doctor` to migrate).",
+    },
+    {
+        path: ["agent", "modelFallbacks"],
+        message: "agent.modelFallbacks was replaced by agent.model.fallbacks (run `nexus doctor` to migrate).",
+    },
+    {
+        path: ["agent", "imageModelFallbacks"],
+        message: "agent.imageModelFallbacks was replaced by agent.imageModel.fallbacks (run `nexus doctor` to migrate).",
+    },
+    {
+        path: ["agent", "bash"],
+        message: "agent.bash was renamed to agent.exec (run `nexus doctor` to migrate).",
+    },
+];
+const LEGACY_CONFIG_MIGRATIONS = [
+    {
+        id: "routing.allowFrom->whatsapp.allowFrom",
+        describe: "Move routing.allowFrom to whatsapp.allowFrom",
+        apply: (raw, changes) => {
+            const routing = raw.routing;
+            if (!routing || typeof routing !== "object")
+                return;
+            const allowFrom = routing.allowFrom;
+            if (allowFrom === undefined)
+                return;
+            const whatsapp = raw.whatsapp && typeof raw.whatsapp === "object"
+                ? raw.whatsapp
+                : {};
+            if (whatsapp.allowFrom === undefined) {
+                whatsapp.allowFrom = allowFrom;
+                changes.push("Moved routing.allowFrom → whatsapp.allowFrom.");
+            }
+            else {
+                changes.push("Removed routing.allowFrom (whatsapp.allowFrom already set).");
+            }
+            delete routing.allowFrom;
+            if (Object.keys(routing).length === 0) {
+                delete raw.routing;
+            }
+            raw.whatsapp = whatsapp;
+        },
+    },
+    {
+        id: "routing.groupChat.requireMention->groups.*.requireMention",
+        describe: "Move routing.groupChat.requireMention to whatsapp/telegram/imessage groups",
+        apply: (raw, changes) => {
+            const routing = raw.routing;
+            if (!routing || typeof routing !== "object")
+                return;
+            const groupChat = routing.groupChat &&
+                typeof routing.groupChat === "object"
+                ? routing.groupChat
+                : null;
+            if (!groupChat)
+                return;
+            const requireMention = groupChat.requireMention;
+            if (requireMention === undefined)
+                return;
+            const applyTo = (key) => {
+                const section = raw[key] && typeof raw[key] === "object"
+                    ? raw[key]
+                    : {};
+                const groups = section.groups && typeof section.groups === "object"
+                    ? section.groups
+                    : {};
+                const defaultKey = "*";
+                const entry = groups[defaultKey] && typeof groups[defaultKey] === "object"
+                    ? groups[defaultKey]
+                    : {};
+                if (entry.requireMention === undefined) {
+                    entry.requireMention = requireMention;
+                    groups[defaultKey] = entry;
+                    section.groups = groups;
+                    raw[key] = section;
+                    changes.push(`Moved routing.groupChat.requireMention → ${key}.groups."*".requireMention.`);
+                }
+                else {
+                    changes.push(`Removed routing.groupChat.requireMention (${key}.groups."*" already set).`);
+                }
+            };
+            applyTo("whatsapp");
+            applyTo("telegram");
+            applyTo("imessage");
+            delete groupChat.requireMention;
+            if (Object.keys(groupChat).length === 0) {
+                delete routing.groupChat;
+            }
+            if (Object.keys(routing).length === 0) {
+                delete raw.routing;
+            }
+        },
+    },
+    {
+        id: "routing.bindings.provider->channel",
+        describe: "Move routing.bindings.match.provider to match.channel",
+        apply: (raw, changes) => {
+            const routing = raw.routing;
+            if (!routing || typeof routing !== "object")
+                return;
+            const bindings = routing.bindings;
+            if (!Array.isArray(bindings))
+                return;
+            let touched = false;
+            for (const entry of bindings) {
+                if (!entry || typeof entry !== "object")
+                    continue;
+                const match = entry.match;
+                if (!match || typeof match !== "object")
+                    continue;
+                const matchRecord = match;
+                if (matchRecord.channel === undefined && matchRecord.provider !== undefined) {
+                    matchRecord.channel = matchRecord.provider;
+                    delete matchRecord.provider;
+                    touched = true;
+                }
+                else if (matchRecord.provider !== undefined) {
+                    delete matchRecord.provider;
+                    touched = true;
+                }
+            }
+            if (touched) {
+                changes.push("Moved routing.bindings.match.provider → routing.bindings.match.channel.");
+            }
+        },
+    },
+    {
+        id: "routing.queue.byProvider->byChannel",
+        describe: "Move routing.queue.byProvider to routing.queue.byChannel",
+        apply: (raw, changes) => {
+            const routing = raw.routing;
+            if (!routing || typeof routing !== "object")
+                return;
+            const queue = routing.queue &&
+                typeof routing.queue === "object"
+                ? routing.queue
+                : null;
+            if (!queue)
+                return;
+            if (queue.byProvider === undefined)
+                return;
+            if (queue.byChannel === undefined) {
+                queue.byChannel = queue.byProvider;
+                changes.push("Moved routing.queue.byProvider → routing.queue.byChannel.");
+            }
+            else {
+                changes.push("Removed routing.queue.byProvider (routing.queue.byChannel already set).");
+            }
+            delete queue.byProvider;
+        },
+    },
+    {
+        id: "session.sendPolicy.match.provider->channel",
+        describe: "Move session.sendPolicy.rules.match.provider to match.channel",
+        apply: (raw, changes) => {
+            const session = raw.session;
+            if (!session || typeof session !== "object")
+                return;
+            const sendPolicy = session.sendPolicy &&
+                typeof session.sendPolicy === "object"
+                ? session.sendPolicy
+                : null;
+            if (!sendPolicy)
+                return;
+            const rules = sendPolicy.rules;
+            if (!Array.isArray(rules))
+                return;
+            let touched = false;
+            for (const rule of rules) {
+                if (!rule || typeof rule !== "object")
+                    continue;
+                const match = rule.match;
+                if (!match || typeof match !== "object")
+                    continue;
+                const matchRecord = match;
+                if (matchRecord.channel === undefined && matchRecord.provider !== undefined) {
+                    matchRecord.channel = matchRecord.provider;
+                    delete matchRecord.provider;
+                    touched = true;
+                }
+                else if (matchRecord.provider !== undefined) {
+                    delete matchRecord.provider;
+                    touched = true;
+                }
+            }
+            if (touched) {
+                changes.push("Moved session.sendPolicy.rules.match.provider → session.sendPolicy.rules.match.channel.");
+            }
+        },
+    },
+    {
+        id: "telegram.requireMention->telegram.groups.*.requireMention",
+        describe: "Move telegram.requireMention to telegram.groups.*.requireMention",
+        apply: (raw, changes) => {
+            const telegram = raw.telegram;
+            if (!telegram || typeof telegram !== "object")
+                return;
+            const requireMention = telegram
+                .requireMention;
+            if (requireMention === undefined)
+                return;
+            const groups = telegram.groups &&
+                typeof telegram.groups === "object"
+                ? telegram.groups
+                : {};
+            const defaultKey = "*";
+            const entry = groups[defaultKey] && typeof groups[defaultKey] === "object"
+                ? groups[defaultKey]
+                : {};
+            if (entry.requireMention === undefined) {
+                entry.requireMention = requireMention;
+                groups[defaultKey] = entry;
+                telegram.groups = groups;
+                changes.push('Moved telegram.requireMention → telegram.groups."*".requireMention.');
+            }
+            else {
+                changes.push('Removed telegram.requireMention (telegram.groups."*" already set).');
+            }
+            delete telegram.requireMention;
+            if (Object.keys(telegram).length === 0) {
+                delete raw.telegram;
+            }
+        },
+    },
+    {
+        id: "agent.model-config-v2",
+        describe: "Migrate legacy agent.model/allowedModels/modelAliases/modelFallbacks/imageModelFallbacks to agent.models + model lists",
+        apply: (raw, changes) => {
+            const agent = raw.agent && typeof raw.agent === "object"
+                ? raw.agent
+                : null;
+            if (!agent)
+                return;
+            const legacyModel = typeof agent.model === "string" ? String(agent.model) : undefined;
+            const legacyImageModel = typeof agent.imageModel === "string"
+                ? String(agent.imageModel)
+                : undefined;
+            const legacyAllowed = Array.isArray(agent.allowedModels)
+                ? agent.allowedModels.map(String)
+                : [];
+            const legacyModelFallbacks = Array.isArray(agent.modelFallbacks)
+                ? agent.modelFallbacks.map(String)
+                : [];
+            const legacyImageModelFallbacks = Array.isArray(agent.imageModelFallbacks)
+                ? agent.imageModelFallbacks.map(String)
+                : [];
+            const legacyAliases = agent.modelAliases && typeof agent.modelAliases === "object"
+                ? agent.modelAliases
+                : {};
+            const hasLegacy = legacyModel ||
+                legacyImageModel ||
+                legacyAllowed.length > 0 ||
+                legacyModelFallbacks.length > 0 ||
+                legacyImageModelFallbacks.length > 0 ||
+                Object.keys(legacyAliases).length > 0;
+            if (!hasLegacy)
+                return;
+            const models = agent.models && typeof agent.models === "object"
+                ? agent.models
+                : {};
+            const ensureModel = (rawKey) => {
+                if (typeof rawKey !== "string")
+                    return;
+                const key = rawKey.trim();
+                if (!key)
+                    return;
+                if (!models[key])
+                    models[key] = {};
+            };
+            ensureModel(legacyModel);
+            ensureModel(legacyImageModel);
+            for (const key of legacyAllowed)
+                ensureModel(key);
+            for (const key of legacyModelFallbacks)
+                ensureModel(key);
+            for (const key of legacyImageModelFallbacks)
+                ensureModel(key);
+            for (const target of Object.values(legacyAliases)) {
+                if (typeof target !== "string")
+                    continue;
+                ensureModel(target);
+            }
+            for (const [alias, targetRaw] of Object.entries(legacyAliases)) {
+                if (typeof targetRaw !== "string")
+                    continue;
+                const target = targetRaw.trim();
+                if (!target)
+                    continue;
+                const entry = models[target] && typeof models[target] === "object"
+                    ? models[target]
+                    : {};
+                if (!("alias" in entry)) {
+                    entry.alias = alias;
+                    models[target] = entry;
+                }
+            }
+            const currentModel = agent.model && typeof agent.model === "object"
+                ? agent.model
+                : null;
+            if (currentModel) {
+                if (!currentModel.primary && legacyModel) {
+                    currentModel.primary = legacyModel;
+                }
+                if (legacyModelFallbacks.length > 0 &&
+                    (!Array.isArray(currentModel.fallbacks) ||
+                        currentModel.fallbacks.length === 0)) {
+                    currentModel.fallbacks = legacyModelFallbacks;
+                }
+                agent.model = currentModel;
+            }
+            else if (legacyModel || legacyModelFallbacks.length > 0) {
+                agent.model = {
+                    primary: legacyModel,
+                    fallbacks: legacyModelFallbacks.length ? legacyModelFallbacks : [],
+                };
+            }
+            const currentImageModel = agent.imageModel && typeof agent.imageModel === "object"
+                ? agent.imageModel
+                : null;
+            if (currentImageModel) {
+                if (!currentImageModel.primary && legacyImageModel) {
+                    currentImageModel.primary = legacyImageModel;
+                }
+                if (legacyImageModelFallbacks.length > 0 &&
+                    (!Array.isArray(currentImageModel.fallbacks) ||
+                        currentImageModel.fallbacks.length === 0)) {
+                    currentImageModel.fallbacks = legacyImageModelFallbacks;
+                }
+                agent.imageModel = currentImageModel;
+            }
+            else if (legacyImageModel || legacyImageModelFallbacks.length > 0) {
+                agent.imageModel = {
+                    primary: legacyImageModel,
+                    fallbacks: legacyImageModelFallbacks.length
+                        ? legacyImageModelFallbacks
+                        : [],
+                };
+            }
+            agent.models = models;
+            if (legacyModel !== undefined) {
+                changes.push("Migrated agent.model string → agent.model.primary.");
+            }
+            if (legacyModelFallbacks.length > 0) {
+                changes.push("Migrated agent.modelFallbacks → agent.model.fallbacks.");
+            }
+            if (legacyImageModel !== undefined) {
+                changes.push("Migrated agent.imageModel string → agent.imageModel.primary.");
+            }
+            if (legacyImageModelFallbacks.length > 0) {
+                changes.push("Migrated agent.imageModelFallbacks → agent.imageModel.fallbacks.");
+            }
+            if (legacyAllowed.length > 0) {
+                changes.push("Migrated agent.allowedModels → agent.models.");
+            }
+            if (Object.keys(legacyAliases).length > 0) {
+                changes.push("Migrated agent.modelAliases → agent.models.*.alias.");
+            }
+            delete agent.allowedModels;
+            delete agent.modelAliases;
+            delete agent.modelFallbacks;
+            delete agent.imageModelFallbacks;
+        },
+    },
+];
+export function findLegacyConfigIssues(raw) {
+    if (!raw || typeof raw !== "object")
+        return [];
+    const root = raw;
+    const issues = [];
+    for (const rule of LEGACY_CONFIG_RULES) {
+        let cursor = root;
+        for (const key of rule.path) {
+            if (!cursor || typeof cursor !== "object") {
+                cursor = undefined;
+                break;
+            }
+            cursor = cursor[key];
+        }
+        if (cursor !== undefined && (!rule.match || rule.match(cursor, root))) {
+            issues.push({ path: rule.path.join("."), message: rule.message });
+        }
+    }
+    return issues;
+}
+export function applyLegacyMigrations(raw) {
+    if (!raw || typeof raw !== "object")
+        return { next: null, changes: [] };
+    const next = structuredClone(raw);
+    const changes = [];
+    for (const migration of LEGACY_CONFIG_MIGRATIONS) {
+        migration.apply(next, changes);
+    }
+    if (changes.length === 0)
+        return { next: null, changes: [] };
+    return { next, changes };
+}

package/dist/config/paths.js

@@ -0,0 +1,82 @@
+import os from "node:os";
+import path from "node:path";
+/**
+ * Nix mode detection: When NEXUS_NIX_MODE=1, the gateway is running under Nix.
+ * In this mode:
+ * - No auto-install flows should be attempted
+ * - Missing dependencies should produce actionable Nix-specific error messages
+ * - Config is managed externally (read-only from Nix perspective)
+ */
+export function resolveIsNixMode(env = process.env) {
+    return env.NEXUS_NIX_MODE === "1";
+}
+export const isNixMode = resolveIsNixMode();
+/**
+ * State directory for mutable data (sessions, logs, caches).
+ * Can be overridden via NEXUS_STATE_DIR.
+ * Default: ~/nexus/state
+ */
+export function resolveStateDir(env = process.env, homedir = os.homedir) {
+    const override = env.NEXUS_STATE_DIR?.trim();
+    if (override)
+        return resolveUserPath(override);
+    return path.join(homedir(), "nexus", "state");
+}
+function resolveUserPath(input) {
+    const trimmed = input.trim();
+    if (!trimmed)
+        return trimmed;
+    if (trimmed.startsWith("~")) {
+        return path.resolve(trimmed.replace("~", os.homedir()));
+    }
+    return path.resolve(trimmed);
+}
+export const STATE_DIR_NEXUS = resolveStateDir();
+/**
+ * Config file path (JSON5).
+ * Can be overridden via NEXUS_CONFIG_PATH.
+ * Default: $NEXUS_STATE_DIR/nexus/config.json
+ */
+export function resolveConfigPath(env = process.env, stateDir = resolveStateDir(env, os.homedir)) {
+    const override = env.NEXUS_CONFIG_PATH?.trim();
+    if (override)
+        return resolveUserPath(override);
+    return path.join(stateDir, "nexus", "config.json");
+}
+export const CONFIG_PATH_NEXUS = resolveConfigPath();
+export const DEFAULT_GATEWAY_PORT = 18789;
+/**
+ * Credentials root directory.
+ */
+export function resolveCredentialsDir(env = process.env, stateDir = resolveStateDir(env, os.homedir)) {
+    const override = env.NEXUS_CREDENTIALS_DIR?.trim();
+    if (override)
+        return resolveUserPath(override);
+    return path.join(stateDir, "credentials");
+}
+const OAUTH_FILENAME = "oauth.json";
+/** @deprecated Use resolveCredentialsDir. */
+export function resolveOAuthDir(env = process.env, stateDir = resolveStateDir(env, os.homedir)) {
+    const override = env.NEXUS_OAUTH_DIR?.trim();
+    if (override)
+        return resolveUserPath(override);
+    return resolveCredentialsDir(env, stateDir);
+}
+/** @deprecated Legacy oauth.json path (deprecated). */
+export function resolveOAuthPath(env = process.env, stateDir = resolveStateDir(env, os.homedir)) {
+    return path.join(resolveOAuthDir(env, stateDir), OAUTH_FILENAME);
+}
+export function resolveGatewayPort(cfg, env = process.env) {
+    const envRaw = env.NEXUS_GATEWAY_PORT?.trim();
+    if (envRaw) {
+        const parsed = Number.parseInt(envRaw, 10);
+        if (Number.isFinite(parsed) && parsed > 0)
+            return parsed;
+    }
+    const configPort = cfg?.gateway?.port;
+    if (typeof configPort === "number" && Number.isFinite(configPort)) {
+        if (configPort > 0)
+            return configPort;
+    }
+    return DEFAULT_GATEWAY_PORT;
+}

package/dist/config/port-defaults.js

@@ -0,0 +1,32 @@
+function isValidPort(port) {
+    return Number.isFinite(port) && port > 0 && port <= 65535;
+}
+function clampPort(port, fallback) {
+    return isValidPort(port) ? port : fallback;
+}
+function derivePort(base, offset, fallback) {
+    return clampPort(base + offset, fallback);
+}
+export const DEFAULT_BRIDGE_PORT = 18790;
+export const DEFAULT_BROWSER_CONTROL_PORT = 18791;
+export const DEFAULT_CANVAS_HOST_PORT = 18793;
+export const DEFAULT_BROWSER_CDP_PORT_RANGE_START = 18800;
+export const DEFAULT_BROWSER_CDP_PORT_RANGE_END = 18899;
+export function deriveDefaultBridgePort(gatewayPort) {
+    return derivePort(gatewayPort, 1, DEFAULT_BRIDGE_PORT);
+}
+export function deriveDefaultBrowserControlPort(gatewayPort) {
+    return derivePort(gatewayPort, 2, DEFAULT_BROWSER_CONTROL_PORT);
+}
+export function deriveDefaultCanvasHostPort(gatewayPort) {
+    return derivePort(gatewayPort, 4, DEFAULT_CANVAS_HOST_PORT);
+}
+export function deriveDefaultBrowserCdpPortRange(browserControlPort) {
+    const start = derivePort(browserControlPort, 9, DEFAULT_BROWSER_CDP_PORT_RANGE_START);
+    const end = clampPort(start +
+        (DEFAULT_BROWSER_CDP_PORT_RANGE_END -
+            DEFAULT_BROWSER_CDP_PORT_RANGE_START), DEFAULT_BROWSER_CDP_PORT_RANGE_END);
+    if (end < start)
+        return { start, end: start };
+    return { start, end };
+}