@intent-systems/nexus 2026.1.5-3

package/dist/commands/update.js

@@ -0,0 +1,16 @@
+import { defaultRuntime } from "../runtime.js";
+import { runConfigureWizard } from "./configure.js";
+export async function updateCommand(runtime = defaultRuntime) {
+    await runConfigureWizard({
+        command: "update",
+        sections: [
+            "workspace",
+            "model",
+            "gateway",
+            "daemon",
+            "providers",
+            "skills",
+            "health",
+        ],
+    }, runtime);
+}

package/dist/commands/usage-upload.js

@@ -0,0 +1,27 @@
+import { defaultRuntime } from "../runtime.js";
+import { runUsageUpload } from "../infra/usage-upload.js";
+export async function usageUploadCommand(opts, runtime = defaultRuntime) {
+    const result = await runUsageUpload({
+        limit: opts.limit,
+        dryRun: opts.dryRun,
+        flush: opts.flush,
+        onlyFlush: opts.onlyFlush,
+    });
+    if (opts.json) {
+        runtime.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    if (result.status === "dry_run") {
+        runtime.log(`\nUsage upload dry run`);
+        runtime.log(`  events: ${result.events ?? 0}`);
+        runtime.log(`  batch_created: ${result.batchCreated ? "yes" : "no"}`);
+        return;
+    }
+    if (result.status === "flush") {
+        runtime.log(`\nUsage upload outbox`);
+        runtime.log(`  attempted: ${result.attempted ?? 0}`);
+        runtime.log(`  uploaded: ${result.uploaded ?? 0}`);
+        return;
+    }
+    runtime.log("\nUsage upload complete");
+}

package/dist/config/config.js

@@ -0,0 +1,6 @@
+export { createConfigIO, loadConfig, parseConfigJson5, readConfigFileSnapshot, writeConfigFile, } from "./io.js";
+export { migrateLegacyConfig } from "./legacy-migrate.js";
+export * from "./paths.js";
+export * from "./types.js";
+export { validateConfigObject } from "./validation.js";
+export { NexusSchema } from "./zod-schema.js";

package/dist/config/defaults.js

@@ -0,0 +1,140 @@
+import { resolveTalkApiKey } from "./talk.js";
+let defaultWarnState = { warned: false };
+const DEFAULT_MODEL_ALIASES = {
+    // Anthropic (pi-ai catalog uses "latest" ids without date suffix)
+    opus: "anthropic/claude-opus-4-5",
+    sonnet: "anthropic/claude-sonnet-4-5",
+    // OpenAI
+    gpt: "openai/gpt-5.2",
+    "gpt-mini": "openai/gpt-5-mini",
+    // Google Gemini (3.x are preview ids in the catalog)
+    gemini: "google/gemini-3-pro-preview",
+    "gemini-flash": "google/gemini-3-flash-preview",
+};
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+export function applyIdentityDefaults(cfg) {
+    const identity = cfg.identity;
+    if (!identity)
+        return cfg;
+    const name = identity.name?.trim();
+    const routing = cfg.routing ?? {};
+    const groupChat = routing.groupChat ?? {};
+    let mutated = false;
+    const next = { ...cfg };
+    if (name && !groupChat.mentionPatterns) {
+        const parts = name.split(/\s+/).filter(Boolean).map(escapeRegExp);
+        const re = parts.length ? parts.join("\\s+") : escapeRegExp(name);
+        const pattern = `\\b@?${re}\\b`;
+        next.routing = {
+            ...(next.routing ?? routing),
+            groupChat: { ...groupChat, mentionPatterns: [pattern] },
+        };
+        mutated = true;
+    }
+    return mutated ? next : cfg;
+}
+export function applyMessageDefaults(cfg) {
+    const messages = cfg.messages;
+    const hasAckReaction = messages?.ackReaction !== undefined;
+    const hasAckScope = messages?.ackReactionScope !== undefined;
+    if (hasAckReaction && hasAckScope)
+        return cfg;
+    const fallbackEmoji = cfg.identity?.emoji?.trim() || "👀";
+    const nextMessages = messages ? { ...messages } : {};
+    let mutated = false;
+    if (!hasAckReaction) {
+        nextMessages.ackReaction = fallbackEmoji;
+        mutated = true;
+    }
+    if (!hasAckScope) {
+        nextMessages.ackReactionScope = "group-mentions";
+        mutated = true;
+    }
+    if (!mutated)
+        return cfg;
+    return {
+        ...cfg,
+        messages: nextMessages,
+    };
+}
+export function applySessionDefaults(cfg, options = {}) {
+    const session = cfg.session;
+    if (!session || session.mainKey === undefined)
+        return cfg;
+    const trimmed = session.mainKey.trim();
+    const warn = options.warn ?? console.warn;
+    const warnState = options.warnState ?? defaultWarnState;
+    const next = {
+        ...cfg,
+        session: { ...session, mainKey: "main" },
+    };
+    if (trimmed && trimmed !== "main" && !warnState.warned) {
+        warnState.warned = true;
+        warn('session.mainKey is ignored; main session is always "main".');
+    }
+    return next;
+}
+export function applyTalkApiKey(config) {
+    const resolved = resolveTalkApiKey();
+    if (!resolved)
+        return config;
+    const existing = config.talk?.apiKey?.trim();
+    if (existing)
+        return config;
+    return {
+        ...config,
+        talk: {
+            ...config.talk,
+            apiKey: resolved,
+        },
+    };
+}
+export function applyModelDefaults(cfg) {
+    const existingAgent = cfg.agent;
+    if (!existingAgent)
+        return cfg;
+    const existingModels = existingAgent.models ?? {};
+    if (Object.keys(existingModels).length === 0)
+        return cfg;
+    let mutated = false;
+    const nextModels = {
+        ...existingModels,
+    };
+    for (const [alias, target] of Object.entries(DEFAULT_MODEL_ALIASES)) {
+        const entry = nextModels[target];
+        if (!entry)
+            continue;
+        if (entry.alias !== undefined)
+            continue;
+        nextModels[target] = { ...entry, alias };
+        mutated = true;
+    }
+    if (!mutated)
+        return cfg;
+    return {
+        ...cfg,
+        agent: {
+            ...existingAgent,
+            models: nextModels,
+        },
+    };
+}
+export function applyLoggingDefaults(cfg) {
+    const logging = cfg.logging;
+    if (!logging)
+        return cfg;
+    if (logging.redactSensitive)
+        return cfg;
+    return {
+        ...cfg,
+        logging: {
+            ...logging,
+            redactSensitive: "tools",
+        },
+    };
+}
+export function resetSessionDefaultsWarningForTests() {
+    defaultWarnState = { warned: false };
+}

package/dist/config/group-policy.js

@@ -0,0 +1,49 @@
+function resolveProviderGroups(cfg, provider) {
+    if (provider === "whatsapp")
+        return cfg.whatsapp?.groups;
+    if (provider === "telegram")
+        return cfg.telegram?.groups;
+    if (provider === "imessage")
+        return cfg.imessage?.groups;
+    return undefined;
+}
+export function resolveProviderGroupPolicy(params) {
+    const { cfg, provider } = params;
+    const groups = resolveProviderGroups(cfg, provider);
+    const allowlistEnabled = Boolean(groups && Object.keys(groups).length > 0);
+    const normalizedId = params.groupId?.trim();
+    const groupConfig = normalizedId && groups ? groups[normalizedId] : undefined;
+    const defaultConfig = groups?.["*"];
+    const allowAll = allowlistEnabled && Boolean(groups && Object.hasOwn(groups, "*"));
+    const allowed = !allowlistEnabled ||
+        allowAll ||
+        (normalizedId
+            ? Boolean(groups && Object.hasOwn(groups, normalizedId))
+            : false);
+    return {
+        allowlistEnabled,
+        allowed,
+        groupConfig,
+        defaultConfig,
+    };
+}
+export function resolveProviderGroupRequireMention(params) {
+    const { requireMentionOverride, overrideOrder = "after-config" } = params;
+    const { groupConfig, defaultConfig } = resolveProviderGroupPolicy(params);
+    const configMention = typeof groupConfig?.requireMention === "boolean"
+        ? groupConfig.requireMention
+        : typeof defaultConfig?.requireMention === "boolean"
+            ? defaultConfig.requireMention
+            : undefined;
+    if (overrideOrder === "before-config" &&
+        typeof requireMentionOverride === "boolean") {
+        return requireMentionOverride;
+    }
+    if (typeof configMention === "boolean")
+        return configMention;
+    if (overrideOrder !== "before-config" &&
+        typeof requireMentionOverride === "boolean") {
+        return requireMentionOverride;
+    }
+    return true;
+}

package/dist/config/includes.js

@@ -0,0 +1,183 @@
+/**
+ * Config includes: $include directive for modular configs
+ *
+ * @example
+ * ```json5
+ * {
+ *   "$include": "./base.json5",           // single file
+ *   "$include": ["./a.json5", "./b.json5"] // merge multiple
+ * }
+ * ```
+ */
+import fs from "node:fs";
+import path from "node:path";
+import JSON5 from "json5";
+export const INCLUDE_KEY = "$include";
+export const MAX_INCLUDE_DEPTH = 10;
+// ============================================================================
+// Errors
+// ============================================================================
+export class ConfigIncludeError extends Error {
+    includePath;
+    cause;
+    constructor(message, includePath, cause) {
+        super(message);
+        this.includePath = includePath;
+        this.cause = cause;
+        this.name = "ConfigIncludeError";
+    }
+}
+export class CircularIncludeError extends ConfigIncludeError {
+    chain;
+    constructor(chain) {
+        super(`Circular include detected: ${chain.join(" -> ")}`, chain[chain.length - 1]);
+        this.chain = chain;
+        this.name = "CircularIncludeError";
+    }
+}
+// ============================================================================
+// Utilities
+// ============================================================================
+function isPlainObject(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        Object.prototype.toString.call(value) === "[object Object]");
+}
+/** Deep merge: arrays concatenate, objects merge recursively, primitives: source wins */
+export function deepMerge(target, source) {
+    if (Array.isArray(target) && Array.isArray(source)) {
+        return [...target, ...source];
+    }
+    if (isPlainObject(target) && isPlainObject(source)) {
+        const result = { ...target };
+        for (const key of Object.keys(source)) {
+            result[key] = key in result ? deepMerge(result[key], source[key]) : source[key];
+        }
+        return result;
+    }
+    return source;
+}
+// ============================================================================
+// Include Resolver Class
+// ============================================================================
+class IncludeProcessor {
+    basePath;
+    resolver;
+    visited = new Set();
+    depth = 0;
+    constructor(basePath, resolver) {
+        this.basePath = basePath;
+        this.resolver = resolver;
+        this.visited.add(path.normalize(basePath));
+    }
+    process(obj) {
+        if (Array.isArray(obj)) {
+            return obj.map((item) => this.process(item));
+        }
+        if (!isPlainObject(obj)) {
+            return obj;
+        }
+        if (!(INCLUDE_KEY in obj)) {
+            return this.processObject(obj);
+        }
+        return this.processInclude(obj);
+    }
+    processObject(obj) {
+        const result = {};
+        for (const [key, value] of Object.entries(obj)) {
+            result[key] = this.process(value);
+        }
+        return result;
+    }
+    processInclude(obj) {
+        const includeValue = obj[INCLUDE_KEY];
+        const otherKeys = Object.keys(obj).filter((k) => k !== INCLUDE_KEY);
+        const included = this.resolveInclude(includeValue);
+        if (otherKeys.length === 0) {
+            return included;
+        }
+        if (!isPlainObject(included)) {
+            throw new ConfigIncludeError("Sibling keys require included content to be an object", typeof includeValue === "string" ? includeValue : INCLUDE_KEY);
+        }
+        // Merge included content with sibling keys
+        const rest = {};
+        for (const key of otherKeys) {
+            rest[key] = this.process(obj[key]);
+        }
+        return deepMerge(included, rest);
+    }
+    resolveInclude(value) {
+        if (typeof value === "string") {
+            return this.loadFile(value);
+        }
+        if (Array.isArray(value)) {
+            return value.reduce((merged, item) => {
+                if (typeof item !== "string") {
+                    throw new ConfigIncludeError(`Invalid $include array item: expected string, got ${typeof item}`, String(item));
+                }
+                return deepMerge(merged, this.loadFile(item));
+            }, {});
+        }
+        throw new ConfigIncludeError(`Invalid $include value: expected string or array of strings, got ${typeof value}`, String(value));
+    }
+    loadFile(includePath) {
+        const resolvedPath = this.resolvePath(includePath);
+        this.checkCircular(resolvedPath);
+        this.checkDepth(includePath);
+        const raw = this.readFile(includePath, resolvedPath);
+        const parsed = this.parseFile(includePath, resolvedPath, raw);
+        return this.processNested(resolvedPath, parsed);
+    }
+    resolvePath(includePath) {
+        const resolved = path.isAbsolute(includePath)
+            ? includePath
+            : path.resolve(path.dirname(this.basePath), includePath);
+        return path.normalize(resolved);
+    }
+    checkCircular(resolvedPath) {
+        if (this.visited.has(resolvedPath)) {
+            throw new CircularIncludeError([...this.visited, resolvedPath]);
+        }
+    }
+    checkDepth(includePath) {
+        if (this.depth >= MAX_INCLUDE_DEPTH) {
+            throw new ConfigIncludeError(`Maximum include depth (${MAX_INCLUDE_DEPTH}) exceeded at: ${includePath}`, includePath);
+        }
+    }
+    readFile(includePath, resolvedPath) {
+        try {
+            return this.resolver.readFile(resolvedPath);
+        }
+        catch (err) {
+            throw new ConfigIncludeError(`Failed to read include file: ${includePath} (resolved: ${resolvedPath})`, includePath, err instanceof Error ? err : undefined);
+        }
+    }
+    parseFile(includePath, resolvedPath, raw) {
+        try {
+            return this.resolver.parseJson(raw);
+        }
+        catch (err) {
+            throw new ConfigIncludeError(`Failed to parse include file: ${includePath} (resolved: ${resolvedPath})`, includePath, err instanceof Error ? err : undefined);
+        }
+    }
+    processNested(resolvedPath, parsed) {
+        const nested = new IncludeProcessor(resolvedPath, this.resolver);
+        nested.visited = new Set([...this.visited, resolvedPath]);
+        nested.depth = this.depth + 1;
+        return nested.process(parsed);
+    }
+}
+// ============================================================================
+// Public API
+// ============================================================================
+const defaultResolver = {
+    readFile: (p) => fs.readFileSync(p, "utf-8"),
+    parseJson: (raw) => JSON5.parse(raw),
+};
+/**
+ * Resolves all $include directives in a parsed config object.
+ */
+export function resolveConfigIncludes(obj, configPath, resolver = defaultResolver) {
+    return new IncludeProcessor(configPath, resolver).process(obj);
+}

package/dist/config/io.js

@@ -0,0 +1,188 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import JSON5 from "json5";
+import { loadShellEnvFallback, resolveShellEnvFallbackTimeoutMs, shouldEnableShellEnvFallback, } from "../infra/shell-env.js";
+import { applyIdentityDefaults, applyLoggingDefaults, applyMessageDefaults, applyModelDefaults, applySessionDefaults, applyTalkApiKey, } from "./defaults.js";
+import { findLegacyConfigIssues } from "./legacy.js";
+import { CONFIG_PATH_NEXUS, resolveConfigPath, resolveStateDir, } from "./paths.js";
+import { validateConfigObject } from "./validation.js";
+import { NexusSchema } from "./zod-schema.js";
+const SHELL_ENV_EXPECTED_KEYS = [
+    "OPENAI_API_KEY",
+    "ANTHROPIC_API_KEY",
+    "ANTHROPIC_OAUTH_TOKEN",
+    "GEMINI_API_KEY",
+    "ZAI_API_KEY",
+    "MINIMAX_API_KEY",
+    "ELEVENLABS_API_KEY",
+    "TELEGRAM_BOT_TOKEN",
+    "DISCORD_BOT_TOKEN",
+    "SLACK_BOT_TOKEN",
+    "SLACK_APP_TOKEN",
+    "NEXUS_GATEWAY_TOKEN",
+    "NEXUS_GATEWAY_PASSWORD",
+];
+function resolveConfigPathForDeps(deps) {
+    if (deps.configPath)
+        return deps.configPath;
+    return resolveConfigPath(deps.env, resolveStateDir(deps.env, deps.homedir));
+}
+function normalizeDeps(overrides = {}) {
+    return {
+        fs: overrides.fs ?? fs,
+        json5: overrides.json5 ?? JSON5,
+        env: overrides.env ?? process.env,
+        homedir: overrides.homedir ?? os.homedir,
+        configPath: overrides.configPath ?? "",
+        logger: overrides.logger ?? console,
+    };
+}
+export function parseConfigJson5(raw, json5 = JSON5) {
+    try {
+        return { ok: true, parsed: json5.parse(raw) };
+    }
+    catch (err) {
+        return { ok: false, error: String(err) };
+    }
+}
+export function createConfigIO(overrides = {}) {
+    const deps = normalizeDeps(overrides);
+    const configPath = resolveConfigPathForDeps(deps);
+    function loadConfig() {
+        try {
+            if (!deps.fs.existsSync(configPath)) {
+                if (shouldEnableShellEnvFallback(deps.env)) {
+                    loadShellEnvFallback({
+                        enabled: true,
+                        env: deps.env,
+                        expectedKeys: SHELL_ENV_EXPECTED_KEYS,
+                        logger: deps.logger,
+                        timeoutMs: resolveShellEnvFallbackTimeoutMs(deps.env),
+                    });
+                }
+                return {};
+            }
+            const raw = deps.fs.readFileSync(configPath, "utf-8");
+            const parsed = deps.json5.parse(raw);
+            if (typeof parsed !== "object" || parsed === null)
+                return {};
+            const validated = NexusSchema.safeParse(parsed);
+            if (!validated.success) {
+                deps.logger.error("Invalid config:");
+                for (const iss of validated.error.issues) {
+                    deps.logger.error(`- ${iss.path.join(".")}: ${iss.message}`);
+                }
+                return {};
+            }
+            const cfg = applyModelDefaults(applySessionDefaults(applyLoggingDefaults(applyMessageDefaults(applyIdentityDefaults(validated.data)))));
+            const enabled = shouldEnableShellEnvFallback(deps.env) ||
+                cfg.env?.shellEnv?.enabled === true;
+            if (enabled) {
+                loadShellEnvFallback({
+                    enabled: true,
+                    env: deps.env,
+                    expectedKeys: SHELL_ENV_EXPECTED_KEYS,
+                    logger: deps.logger,
+                    timeoutMs: cfg.env?.shellEnv?.timeoutMs ??
+                        resolveShellEnvFallbackTimeoutMs(deps.env),
+                });
+            }
+            return cfg;
+        }
+        catch (err) {
+            deps.logger.error(`Failed to read config at ${configPath}`, err);
+            return {};
+        }
+    }
+    async function readConfigFileSnapshot() {
+        const exists = deps.fs.existsSync(configPath);
+        if (!exists) {
+            const config = applyTalkApiKey(applyModelDefaults(applySessionDefaults(applyMessageDefaults({}))));
+            const legacyIssues = [];
+            return {
+                path: configPath,
+                exists: false,
+                raw: null,
+                parsed: {},
+                valid: true,
+                config,
+                issues: [],
+                legacyIssues,
+            };
+        }
+        try {
+            const raw = deps.fs.readFileSync(configPath, "utf-8");
+            const parsedRes = parseConfigJson5(raw, deps.json5);
+            if (!parsedRes.ok) {
+                return {
+                    path: configPath,
+                    exists: true,
+                    raw,
+                    parsed: {},
+                    valid: false,
+                    config: {},
+                    issues: [
+                        { path: "", message: `JSON5 parse failed: ${parsedRes.error}` },
+                    ],
+                    legacyIssues: [],
+                };
+            }
+            const legacyIssues = findLegacyConfigIssues(parsedRes.parsed);
+            const validated = validateConfigObject(parsedRes.parsed);
+            if (!validated.ok) {
+                return {
+                    path: configPath,
+                    exists: true,
+                    raw,
+                    parsed: parsedRes.parsed,
+                    valid: false,
+                    config: {},
+                    issues: validated.issues,
+                    legacyIssues,
+                };
+            }
+            return {
+                path: configPath,
+                exists: true,
+                raw,
+                parsed: parsedRes.parsed,
+                valid: true,
+                config: applyTalkApiKey(applyModelDefaults(applySessionDefaults(applyLoggingDefaults(applyMessageDefaults(validated.config))))),
+                issues: [],
+                legacyIssues,
+            };
+        }
+        catch (err) {
+            return {
+                path: configPath,
+                exists: true,
+                raw: null,
+                parsed: {},
+                valid: false,
+                config: {},
+                issues: [{ path: "", message: `read failed: ${String(err)}` }],
+                legacyIssues: [],
+            };
+        }
+    }
+    async function writeConfigFile(cfg) {
+        await deps.fs.promises.mkdir(path.dirname(configPath), {
+            recursive: true,
+        });
+        const json = JSON.stringify(applyModelDefaults(cfg), null, 2)
+            .trimEnd()
+            .concat("\n");
+        await deps.fs.promises.writeFile(configPath, json, "utf-8");
+    }
+    return {
+        configPath,
+        loadConfig,
+        readConfigFileSnapshot,
+        writeConfigFile,
+    };
+}
+const defaultIO = createConfigIO({ configPath: CONFIG_PATH_NEXUS });
+export const loadConfig = defaultIO.loadConfig;
+export const readConfigFileSnapshot = defaultIO.readConfigFileSnapshot;
+export const writeConfigFile = defaultIO.writeConfigFile;

package/dist/config/legacy-migrate.js

@@ -0,0 +1,13 @@
+import { applyLegacyMigrations } from "./legacy.js";
+import { validateConfigObject } from "./validation.js";
+export function migrateLegacyConfig(raw) {
+    const { next, changes } = applyLegacyMigrations(raw);
+    if (!next)
+        return { config: null, changes: [] };
+    const validated = validateConfigObject(next);
+    if (!validated.ok) {
+        changes.push("Migration applied, but config still invalid; fix remaining issues manually.");
+        return { config: null, changes };
+    }
+    return { config: validated.config, changes };
+}