@intent-systems/nexus 2026.1.5-3 → 2026.1.5-4

package/dist/plugins/loader.js

@@ -0,0 +1,290 @@
+import { createJiti } from "jiti";
+import { createSubsystemLogger } from "../logging.js";
+import { resolveUserPath } from "../utils.js";
+import { discoverNexusPlugins } from "./discovery.js";
+import { createPluginRegistry, } from "./registry.js";
+const registryCache = new Map();
+const defaultLogger = () => createSubsystemLogger("plugins");
+const normalizeList = (value) => {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .map((entry) => (typeof entry === "string" ? entry.trim() : ""))
+        .filter(Boolean);
+};
+const normalizePluginEntries = (entries) => {
+    if (!entries || typeof entries !== "object" || Array.isArray(entries)) {
+        return {};
+    }
+    const normalized = {};
+    for (const [key, value] of Object.entries(entries)) {
+        if (!key.trim())
+            continue;
+        if (!value || typeof value !== "object" || Array.isArray(value)) {
+            normalized[key] = {};
+            continue;
+        }
+        const entry = value;
+        normalized[key] = {
+            enabled: typeof entry.enabled === "boolean" ? entry.enabled : undefined,
+            config: entry.config &&
+                typeof entry.config === "object" &&
+                !Array.isArray(entry.config)
+                ? entry.config
+                : undefined,
+        };
+    }
+    return normalized;
+};
+const normalizePluginsConfig = (config) => {
+    return {
+        enabled: config?.enabled !== false,
+        allow: normalizeList(config?.allow),
+        deny: normalizeList(config?.deny),
+        loadPaths: normalizeList(config?.load?.paths),
+        entries: normalizePluginEntries(config?.entries),
+    };
+};
+function buildCacheKey(params) {
+    const workspaceKey = params.workspaceDir
+        ? resolveUserPath(params.workspaceDir)
+        : "";
+    return `${workspaceKey}::${JSON.stringify(params.plugins)}`;
+}
+function resolveEnableState(id, config) {
+    if (!config.enabled) {
+        return { enabled: false, reason: "plugins disabled" };
+    }
+    if (config.deny.includes(id)) {
+        return { enabled: false, reason: "blocked by denylist" };
+    }
+    if (config.allow.length > 0 && !config.allow.includes(id)) {
+        return { enabled: false, reason: "not in allowlist" };
+    }
+    const entry = config.entries[id];
+    if (entry?.enabled === false) {
+        return { enabled: false, reason: "disabled in config" };
+    }
+    return { enabled: true };
+}
+function validatePluginConfig(params) {
+    const schema = params.schema;
+    if (!schema)
+        return { ok: true, value: params.value };
+    if (typeof schema.validate === "function") {
+        const result = schema.validate(params.value);
+        if (result.ok) {
+            return { ok: true, value: result.value };
+        }
+        return { ok: false, errors: result.errors };
+    }
+    if (typeof schema.safeParse === "function") {
+        const result = schema.safeParse(params.value);
+        if (result.success) {
+            return { ok: true, value: result.data };
+        }
+        const issues = result.error?.issues ?? [];
+        const errors = issues.map((issue) => {
+            const path = issue.path.length > 0 ? issue.path.join(".") : "<root>";
+            return `${path}: ${issue.message}`;
+        });
+        return { ok: false, errors };
+    }
+    if (typeof schema.parse === "function") {
+        try {
+            const parsed = schema.parse(params.value);
+            return { ok: true, value: parsed };
+        }
+        catch (err) {
+            return { ok: false, errors: [String(err)] };
+        }
+    }
+    return { ok: true, value: params.value };
+}
+function resolvePluginModuleExport(moduleExport) {
+    const resolved = moduleExport &&
+        typeof moduleExport === "object" &&
+        "default" in moduleExport
+        ? moduleExport.default
+        : moduleExport;
+    if (typeof resolved === "function") {
+        return {
+            register: resolved,
+        };
+    }
+    if (resolved && typeof resolved === "object") {
+        const def = resolved;
+        const register = def.register ?? def.activate;
+        return { definition: def, register };
+    }
+    return {};
+}
+function createPluginRecord(params) {
+    return {
+        id: params.id,
+        name: params.name ?? params.id,
+        description: params.description,
+        version: params.version,
+        source: params.source,
+        origin: params.origin,
+        workspaceDir: params.workspaceDir,
+        enabled: params.enabled,
+        status: params.enabled ? "loaded" : "disabled",
+        toolNames: [],
+        gatewayMethods: [],
+        cliCommands: [],
+        services: [],
+        configSchema: params.configSchema,
+        configUiHints: undefined,
+    };
+}
+function pushDiagnostics(diagnostics, append) {
+    diagnostics.push(...append);
+}
+export function loadNexusPlugins(options = {}) {
+    const cfg = options.config ?? {};
+    const logger = options.logger ?? defaultLogger();
+    const normalized = normalizePluginsConfig(cfg.plugins);
+    const cacheKey = buildCacheKey({
+        workspaceDir: options.workspaceDir,
+        plugins: normalized,
+    });
+    const cacheEnabled = options.cache !== false;
+    if (cacheEnabled) {
+        const cached = registryCache.get(cacheKey);
+        if (cached)
+            return cached;
+    }
+    const { registry, createApi } = createPluginRegistry({
+        logger,
+        coreGatewayHandlers: options.coreGatewayHandlers,
+    });
+    const discovery = discoverNexusPlugins({
+        workspaceDir: options.workspaceDir,
+        extraPaths: normalized.loadPaths,
+    });
+    pushDiagnostics(registry.diagnostics, discovery.diagnostics);
+    const jiti = createJiti(import.meta.url, {
+        interopDefault: true,
+    });
+    for (const candidate of discovery.candidates) {
+        const enableState = resolveEnableState(candidate.idHint, normalized);
+        const entry = normalized.entries[candidate.idHint];
+        const record = createPluginRecord({
+            id: candidate.idHint,
+            name: candidate.packageName ?? candidate.idHint,
+            description: candidate.packageDescription,
+            version: candidate.packageVersion,
+            source: candidate.source,
+            origin: candidate.origin,
+            workspaceDir: candidate.workspaceDir,
+            enabled: enableState.enabled,
+            configSchema: false,
+        });
+        if (!enableState.enabled) {
+            record.status = "disabled";
+            record.error = enableState.reason;
+            registry.plugins.push(record);
+            continue;
+        }
+        let mod = null;
+        try {
+            mod = jiti(candidate.source);
+        }
+        catch (err) {
+            record.status = "error";
+            record.error = String(err);
+            registry.plugins.push(record);
+            registry.diagnostics.push({
+                level: "error",
+                pluginId: record.id,
+                source: record.source,
+                message: `failed to load plugin: ${String(err)}`,
+            });
+            continue;
+        }
+        const resolved = resolvePluginModuleExport(mod);
+        const definition = resolved.definition;
+        const register = resolved.register;
+        if (definition?.id && definition.id !== record.id) {
+            registry.diagnostics.push({
+                level: "warn",
+                pluginId: record.id,
+                source: record.source,
+                message: `plugin id mismatch (config uses "${record.id}", export uses "${definition.id}")`,
+            });
+        }
+        record.name = definition?.name ?? record.name;
+        record.description = definition?.description ?? record.description;
+        record.version = definition?.version ?? record.version;
+        record.configSchema = Boolean(definition?.configSchema);
+        record.configUiHints =
+            definition?.configSchema &&
+                typeof definition.configSchema === "object" &&
+                definition.configSchema.uiHints &&
+                typeof definition.configSchema.uiHints ===
+                    "object" &&
+                !Array.isArray(definition.configSchema.uiHints)
+                ? definition.configSchema.uiHints
+                : undefined;
+        const validatedConfig = validatePluginConfig({
+            schema: definition?.configSchema,
+            value: entry?.config,
+        });
+        if (!validatedConfig.ok) {
+            record.status = "error";
+            record.error = `invalid config: ${validatedConfig.errors?.join(", ")}`;
+            registry.plugins.push(record);
+            registry.diagnostics.push({
+                level: "error",
+                pluginId: record.id,
+                source: record.source,
+                message: record.error,
+            });
+            continue;
+        }
+        if (typeof register !== "function") {
+            record.status = "error";
+            record.error = "plugin export missing register/activate";
+            registry.plugins.push(record);
+            registry.diagnostics.push({
+                level: "error",
+                pluginId: record.id,
+                source: record.source,
+                message: record.error,
+            });
+            continue;
+        }
+        const api = createApi(record, {
+            config: cfg,
+            pluginConfig: validatedConfig.value,
+        });
+        try {
+            const result = register(api);
+            if (result && typeof result.then === "function") {
+                registry.diagnostics.push({
+                    level: "warn",
+                    pluginId: record.id,
+                    source: record.source,
+                    message: "plugin register returned a promise; async registration is ignored",
+                });
+            }
+            registry.plugins.push(record);
+        }
+        catch (err) {
+            record.status = "error";
+            record.error = String(err);
+            registry.plugins.push(record);
+            registry.diagnostics.push({
+                level: "error",
+                pluginId: record.id,
+                source: record.source,
+                message: `plugin failed during register: ${String(err)}`,
+            });
+        }
+    }
+    if (cacheEnabled) {
+        registryCache.set(cacheKey, registry);
+    }
+    return registry;
+}

package/dist/plugins/registry.js

@@ -0,0 +1,105 @@
+import { resolveUserPath } from "../utils.js";
+export function createPluginRegistry(registryParams) {
+    const registry = {
+        plugins: [],
+        tools: [],
+        gatewayHandlers: {},
+        cliRegistrars: [],
+        services: [],
+        diagnostics: [],
+    };
+    const coreGatewayMethods = new Set(Object.keys(registryParams.coreGatewayHandlers ?? {}));
+    const pushDiagnostic = (diag) => {
+        registry.diagnostics.push(diag);
+    };
+    const registerTool = (record, tool, opts) => {
+        const names = opts?.names ?? (opts?.name ? [opts.name] : []);
+        const factory = typeof tool === "function"
+            ? tool
+            : (_ctx) => tool;
+        if (typeof tool !== "function") {
+            names.push(tool.name);
+        }
+        const normalized = names.map((name) => name.trim()).filter(Boolean);
+        if (normalized.length > 0) {
+            record.toolNames.push(...normalized);
+        }
+        registry.tools.push({
+            pluginId: record.id,
+            factory,
+            names: normalized,
+            source: record.source,
+        });
+    };
+    const registerGatewayMethod = (record, method, handler) => {
+        const trimmed = method.trim();
+        if (!trimmed)
+            return;
+        if (coreGatewayMethods.has(trimmed) || registry.gatewayHandlers[trimmed]) {
+            pushDiagnostic({
+                level: "error",
+                pluginId: record.id,
+                source: record.source,
+                message: `gateway method already registered: ${trimmed}`,
+            });
+            return;
+        }
+        registry.gatewayHandlers[trimmed] = handler;
+        record.gatewayMethods.push(trimmed);
+    };
+    const registerCli = (record, registrar, opts) => {
+        const commands = (opts?.commands ?? [])
+            .map((cmd) => cmd.trim())
+            .filter(Boolean);
+        record.cliCommands.push(...commands);
+        registry.cliRegistrars.push({
+            pluginId: record.id,
+            register: registrar,
+            commands,
+            source: record.source,
+        });
+    };
+    const registerService = (record, service) => {
+        const id = service.id.trim();
+        if (!id)
+            return;
+        record.services.push(id);
+        registry.services.push({
+            pluginId: record.id,
+            service,
+            source: record.source,
+        });
+    };
+    const normalizeLogger = (logger) => ({
+        info: logger.info,
+        warn: logger.warn,
+        error: logger.error,
+        debug: logger.debug,
+    });
+    const createApi = (record, params) => {
+        return {
+            id: record.id,
+            name: record.name,
+            version: record.version,
+            description: record.description,
+            source: record.source,
+            config: params.config,
+            pluginConfig: params.pluginConfig,
+            logger: normalizeLogger(registryParams.logger),
+            registerTool: (tool, opts) => registerTool(record, tool, opts),
+            registerGatewayMethod: (method, handler) => registerGatewayMethod(record, method, handler),
+            registerCli: (registrar, opts) => registerCli(record, registrar, opts),
+            registerService: (service) => registerService(record, service),
+            resolvePath: (input) => resolveUserPath(input),
+        };
+    };
+    return {
+        registry,
+        createApi,
+        pushDiagnostic,
+        registerTool,
+        registerGatewayMethod,
+        registerCli,
+        registerService,
+    };
+}

package/dist/plugins/status.js

@@ -0,0 +1,29 @@
+import { resolveAgentWorkspaceDir } from "../agents/agent-scope.js";
+import { loadConfig } from "../config/config.js";
+import { createSubsystemLogger } from "../logging.js";
+import { DEFAULT_AGENT_ID, normalizeAgentId } from "../routing/session-key.js";
+import { loadNexusPlugins } from "./loader.js";
+const log = createSubsystemLogger("plugins");
+function resolveDefaultAgentId(cfg) {
+    return normalizeAgentId(cfg.routing?.defaultAgentId ?? DEFAULT_AGENT_ID);
+}
+export function buildPluginStatusReport(params) {
+    const config = params?.config ?? loadConfig();
+    const workspaceDir = params?.workspaceDir
+        ? params.workspaceDir
+        : resolveAgentWorkspaceDir(config, resolveDefaultAgentId(config));
+    const registry = loadNexusPlugins({
+        config,
+        workspaceDir,
+        logger: {
+            info: (msg) => log.info(msg),
+            warn: (msg) => log.warn(msg),
+            error: (msg) => log.error(msg),
+            debug: (msg) => log.debug(msg),
+        },
+    });
+    return {
+        workspaceDir,
+        ...registry,
+    };
+}

package/dist/plugins/tools.js

@@ -0,0 +1,39 @@
+import { createSubsystemLogger } from "../logging.js";
+import { loadNexusPlugins } from "./loader.js";
+const log = createSubsystemLogger("plugins");
+export function resolvePluginTools(params) {
+    const registry = loadNexusPlugins({
+        config: params.context.config,
+        workspaceDir: params.context.workspaceDir,
+        logger: {
+            info: (msg) => log.info(msg),
+            warn: (msg) => log.warn(msg),
+            error: (msg) => log.error(msg),
+            debug: (msg) => log.debug(msg),
+        },
+    });
+    const tools = [];
+    const existing = params.existingToolNames ?? new Set();
+    for (const entry of registry.tools) {
+        let resolved = null;
+        try {
+            resolved = entry.factory(params.context);
+        }
+        catch (err) {
+            log.error(`plugin tool failed (${entry.pluginId}): ${String(err)}`);
+            continue;
+        }
+        if (!resolved)
+            continue;
+        const list = Array.isArray(resolved) ? resolved : [resolved];
+        for (const tool of list) {
+            if (existing.has(tool.name)) {
+                log.warn(`plugin tool name conflict (${entry.pluginId}): ${tool.name}`);
+                continue;
+            }
+            existing.add(tool.name);
+            tools.push(tool);
+        }
+    }
+    return tools;
+}

package/dist/plugins/types.js

@@ -0,0 +1 @@
+export {};

package/dist/routing/resolve-route.js

@@ -0,0 +1,144 @@
+import { buildAgentMainSessionKey, buildAgentPeerSessionKey, DEFAULT_ACCOUNT_ID, DEFAULT_AGENT_ID, DEFAULT_MAIN_KEY, normalizeAgentId, } from "./session-key.js";
+export { DEFAULT_ACCOUNT_ID, DEFAULT_AGENT_ID } from "./session-key.js";
+function normalizeToken(value) {
+    return (value ?? "").trim().toLowerCase();
+}
+function normalizeId(value) {
+    return (value ?? "").trim();
+}
+function normalizeAccountId(value) {
+    const trimmed = (value ?? "").trim();
+    return trimmed ? trimmed : DEFAULT_ACCOUNT_ID;
+}
+function matchesAccountId(match, actual) {
+    const trimmed = (match ?? "").trim();
+    if (!trimmed)
+        return actual === DEFAULT_ACCOUNT_ID;
+    if (trimmed === "*")
+        return true;
+    return trimmed === actual;
+}
+export function buildAgentSessionKey(params) {
+    const provider = normalizeToken(params.provider) || "unknown";
+    const peer = params.peer;
+    return buildAgentPeerSessionKey({
+        agentId: params.agentId,
+        mainKey: DEFAULT_MAIN_KEY,
+        provider,
+        peerKind: peer?.kind ?? "dm",
+        peerId: peer ? normalizeId(peer.id) || "unknown" : null,
+    });
+}
+function listBindings(cfg) {
+    const bindings = cfg.routing?.bindings;
+    return Array.isArray(bindings) ? bindings : [];
+}
+function listAgents(cfg) {
+    const agents = cfg.routing?.agents;
+    return agents && typeof agents === "object" ? agents : undefined;
+}
+function resolveDefaultAgentId(cfg) {
+    const explicit = cfg.routing?.defaultAgentId?.trim();
+    if (explicit)
+        return explicit;
+    return DEFAULT_AGENT_ID;
+}
+function pickFirstExistingAgentId(cfg, agentId) {
+    const normalized = normalizeAgentId(agentId);
+    const agents = listAgents(cfg);
+    if (!agents)
+        return normalized;
+    if (Object.hasOwn(agents, normalized))
+        return normalized;
+    return normalizeAgentId(resolveDefaultAgentId(cfg));
+}
+function matchesProvider(match, provider) {
+    const key = normalizeToken(match?.provider);
+    if (!key)
+        return false;
+    return key === provider;
+}
+function matchesPeer(match, peer) {
+    const m = match?.peer;
+    if (!m)
+        return false;
+    const kind = normalizeToken(m.kind);
+    const id = normalizeId(m.id);
+    if (!kind || !id)
+        return false;
+    return kind === peer.kind && id === peer.id;
+}
+function matchesGuild(match, guildId) {
+    const id = normalizeId(match?.guildId);
+    if (!id)
+        return false;
+    return id === guildId;
+}
+function matchesTeam(match, teamId) {
+    const id = normalizeId(match?.teamId);
+    if (!id)
+        return false;
+    return id === teamId;
+}
+export function resolveAgentRoute(input) {
+    const provider = normalizeToken(input.provider ?? input.channel);
+    const accountId = normalizeAccountId(input.accountId);
+    const peer = input.peer
+        ? { kind: input.peer.kind, id: normalizeId(input.peer.id) }
+        : null;
+    const guildId = normalizeId(input.guildId);
+    const teamId = normalizeId(input.teamId);
+    const bindings = listBindings(input.cfg).filter((binding) => {
+        if (!binding || typeof binding !== "object")
+            return false;
+        if (!matchesProvider(binding.match, provider))
+            return false;
+        return matchesAccountId(binding.match?.accountId, accountId);
+    });
+    const choose = (agentId, matchedBy) => {
+        const resolvedAgentId = pickFirstExistingAgentId(input.cfg, agentId);
+        return {
+            agentId: resolvedAgentId,
+            provider,
+            accountId,
+            sessionKey: buildAgentSessionKey({
+                agentId: resolvedAgentId,
+                provider,
+                peer,
+            }),
+            mainSessionKey: buildAgentMainSessionKey({
+                agentId: resolvedAgentId,
+                mainKey: DEFAULT_MAIN_KEY,
+            }),
+            matchedBy,
+        };
+    };
+    if (peer) {
+        const peerMatch = bindings.find((b) => matchesPeer(b.match, peer));
+        if (peerMatch)
+            return choose(peerMatch.agentId, "binding.peer");
+    }
+    if (guildId) {
+        const guildMatch = bindings.find((b) => matchesGuild(b.match, guildId));
+        if (guildMatch)
+            return choose(guildMatch.agentId, "binding.guild");
+    }
+    if (teamId) {
+        const teamMatch = bindings.find((b) => matchesTeam(b.match, teamId));
+        if (teamMatch)
+            return choose(teamMatch.agentId, "binding.team");
+    }
+    const accountMatch = bindings.find((b) => b.match?.accountId?.trim() !== "*" &&
+        !b.match?.peer &&
+        !b.match?.guildId &&
+        !b.match?.teamId);
+    if (accountMatch)
+        return choose(accountMatch.agentId, "binding.account");
+    const anyAccountMatch = bindings.find((b) => b.match?.accountId?.trim() === "*" &&
+        !b.match?.peer &&
+        !b.match?.guildId &&
+        !b.match?.teamId);
+    if (anyAccountMatch)
+        return choose(anyAccountMatch.agentId, "binding.provider");
+    return choose(resolveDefaultAgentId(input.cfg), "default");
+}

package/dist/routing/session-key.js

@@ -0,0 +1,63 @@
+export const DEFAULT_AGENT_ID = "default";
+export const DEFAULT_MAIN_KEY = "main";
+export const DEFAULT_ACCOUNT_ID = "default";
+export function normalizeAgentId(value) {
+    const trimmed = (value ?? "").trim();
+    if (!trimmed)
+        return DEFAULT_AGENT_ID;
+    // Keep it path-safe + shell-friendly.
+    if (/^[a-z0-9][a-z0-9_-]{0,63}$/i.test(trimmed))
+        return trimmed;
+    // Best-effort fallback: collapse invalid characters to "-"
+    return (trimmed
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, "-")
+        .replace(/^-+/, "")
+        .replace(/-+$/, "")
+        .slice(0, 64) || DEFAULT_AGENT_ID);
+}
+export function parseAgentSessionKey(sessionKey) {
+    const raw = (sessionKey ?? "").trim();
+    if (!raw)
+        return null;
+    const parts = raw.split(":").filter(Boolean);
+    if (parts.length < 3)
+        return null;
+    if (parts[0] !== "agent")
+        return null;
+    const agentId = parts[1]?.trim();
+    const rest = parts.slice(2).join(":");
+    if (!agentId || !rest)
+        return null;
+    return { agentId, rest };
+}
+export function resolveAgentIdFromSessionKey(sessionKey) {
+    const parsed = parseAgentSessionKey(sessionKey);
+    return normalizeAgentId(parsed?.agentId ?? DEFAULT_AGENT_ID);
+}
+export function isSubagentSessionKey(sessionKey) {
+    const raw = (sessionKey ?? "").trim();
+    if (!raw)
+        return false;
+    if (raw.toLowerCase().startsWith("subagent:"))
+        return true;
+    const parsed = parseAgentSessionKey(raw);
+    return Boolean((parsed?.rest ?? "").toLowerCase().startsWith("subagent:"));
+}
+export function buildAgentMainSessionKey(params) {
+    const agentId = normalizeAgentId(params.agentId);
+    const mainKey = (params.mainKey ?? DEFAULT_MAIN_KEY).trim() || DEFAULT_MAIN_KEY;
+    return `agent:${agentId}:${mainKey}`;
+}
+export function buildAgentPeerSessionKey(params) {
+    const peerKind = params.peerKind ?? "dm";
+    if (peerKind === "dm") {
+        return buildAgentMainSessionKey({
+            agentId: params.agentId,
+            mainKey: params.mainKey,
+        });
+    }
+    const provider = (params.provider ?? "").trim().toLowerCase() || "unknown";
+    const peerId = (params.peerId ?? "").trim() || "unknown";
+    return `agent:${normalizeAgentId(params.agentId)}:${provider}:${peerKind}:${peerId}`;
+}