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

package/dist/plugins/install.js

@@ -0,0 +1,181 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { runCommandWithTimeout } from "../process/exec.js";
+import { CONFIG_DIR, resolveUserPath } from "../utils.js";
+const defaultLogger = {};
+function unscopedPackageName(name) {
+    const trimmed = name.trim();
+    if (!trimmed)
+        return trimmed;
+    return trimmed.includes("/")
+        ? (trimmed.split("/").pop() ?? trimmed)
+        : trimmed;
+}
+function safeDirName(input) {
+    const trimmed = input.trim();
+    if (!trimmed)
+        return trimmed;
+    return trimmed.replaceAll("/", "__");
+}
+async function readJsonFile(filePath) {
+    const raw = await fs.readFile(filePath, "utf-8");
+    return JSON.parse(raw);
+}
+async function fileExists(filePath) {
+    try {
+        await fs.stat(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function resolvePackedPackageDir(extractDir) {
+    const direct = path.join(extractDir, "package");
+    if (await fileExists(direct))
+        return direct;
+    const entries = await fs.readdir(extractDir, { withFileTypes: true });
+    const dirs = entries.filter((e) => e.isDirectory()).map((e) => e.name);
+    if (dirs.length !== 1) {
+        throw new Error(`unexpected archive layout (dirs: ${dirs.join(", ")})`);
+    }
+    const onlyDir = dirs[0];
+    if (!onlyDir) {
+        throw new Error("unexpected archive layout (no package dir found)");
+    }
+    return path.join(extractDir, onlyDir);
+}
+async function ensureNexusExtensions(manifest) {
+    // Try nexus first, fall back to clawdbot for backward compat
+    const extensions = manifest.nexus?.extensions ?? manifest.clawdbot?.extensions;
+    if (!Array.isArray(extensions)) {
+        throw new Error("package.json missing nexus.extensions (or clawdbot.extensions)");
+    }
+    const list = extensions
+        .map((e) => (typeof e === "string" ? e.trim() : ""))
+        .filter(Boolean);
+    if (list.length === 0) {
+        throw new Error("package.json nexus.extensions is empty");
+    }
+    return list;
+}
+export async function installPluginFromArchive(params) {
+    const logger = params.logger ?? defaultLogger;
+    const timeoutMs = params.timeoutMs ?? 120_000;
+    const archivePath = resolveUserPath(params.archivePath);
+    if (!(await fileExists(archivePath))) {
+        return { ok: false, error: `archive not found: ${archivePath}` };
+    }
+    const extensionsDir = params.extensionsDir
+        ? resolveUserPath(params.extensionsDir)
+        : path.join(CONFIG_DIR, "extensions");
+    await fs.mkdir(extensionsDir, { recursive: true });
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "nexus-plugin-"));
+    const extractDir = path.join(tmpDir, "extract");
+    await fs.mkdir(extractDir, { recursive: true });
+    logger.info?.(`Extracting ${archivePath}…`);
+    const tarRes = await runCommandWithTimeout(["tar", "-xzf", archivePath, "-C", extractDir], { timeoutMs });
+    if (tarRes.code !== 0) {
+        return {
+            ok: false,
+            error: `failed to extract archive: ${tarRes.stderr.trim() || tarRes.stdout.trim()}`,
+        };
+    }
+    let packageDir = "";
+    try {
+        packageDir = await resolvePackedPackageDir(extractDir);
+    }
+    catch (err) {
+        return { ok: false, error: String(err) };
+    }
+    const manifestPath = path.join(packageDir, "package.json");
+    if (!(await fileExists(manifestPath))) {
+        return { ok: false, error: "extracted package missing package.json" };
+    }
+    let manifest;
+    try {
+        manifest = await readJsonFile(manifestPath);
+    }
+    catch (err) {
+        return { ok: false, error: `invalid package.json: ${String(err)}` };
+    }
+    let extensions;
+    try {
+        extensions = await ensureNexusExtensions(manifest);
+    }
+    catch (err) {
+        return { ok: false, error: String(err) };
+    }
+    const pkgName = typeof manifest.name === "string" ? manifest.name : "";
+    const pluginId = pkgName ? unscopedPackageName(pkgName) : "plugin";
+    const targetDir = path.join(extensionsDir, safeDirName(pluginId));
+    if (await fileExists(targetDir)) {
+        return {
+            ok: false,
+            error: `plugin already exists: ${targetDir} (delete it first)`,
+        };
+    }
+    logger.info?.(`Installing to ${targetDir}…`);
+    await fs.cp(packageDir, targetDir, { recursive: true });
+    for (const entry of extensions) {
+        const resolvedEntry = path.resolve(targetDir, entry);
+        if (!(await fileExists(resolvedEntry))) {
+            logger.warn?.(`extension entry not found: ${entry}`);
+        }
+    }
+    const deps = manifest.dependencies ?? {};
+    const hasDeps = Object.keys(deps).length > 0;
+    if (hasDeps) {
+        logger.info?.("Installing plugin dependencies…");
+        const npmRes = await runCommandWithTimeout(["npm", "install", "--omit=dev", "--silent"], { timeoutMs: Math.max(timeoutMs, 300_000), cwd: targetDir });
+        if (npmRes.code !== 0) {
+            return {
+                ok: false,
+                error: `npm install failed: ${npmRes.stderr.trim() || npmRes.stdout.trim()}`,
+            };
+        }
+    }
+    return {
+        ok: true,
+        pluginId,
+        targetDir,
+        manifestName: pkgName || undefined,
+        extensions,
+    };
+}
+export async function installPluginFromNpmSpec(params) {
+    const logger = params.logger ?? defaultLogger;
+    const timeoutMs = params.timeoutMs ?? 120_000;
+    const spec = params.spec.trim();
+    if (!spec)
+        return { ok: false, error: "missing npm spec" };
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "nexus-npm-pack-"));
+    logger.info?.(`Downloading ${spec}…`);
+    const res = await runCommandWithTimeout(["npm", "pack", spec], {
+        timeoutMs: Math.max(timeoutMs, 300_000),
+        cwd: tmpDir,
+        env: { COREPACK_ENABLE_DOWNLOAD_PROMPT: "0" },
+    });
+    if (res.code !== 0) {
+        return {
+            ok: false,
+            error: `npm pack failed: ${res.stderr.trim() || res.stdout.trim()}`,
+        };
+    }
+    const packed = (res.stdout || "")
+        .split("\n")
+        .map((l) => l.trim())
+        .filter(Boolean)
+        .pop();
+    if (!packed) {
+        return { ok: false, error: "npm pack produced no archive" };
+    }
+    const archivePath = path.join(tmpDir, packed);
+    return await installPluginFromArchive({
+        archivePath,
+        extensionsDir: params.extensionsDir,
+        timeoutMs,
+        logger,
+    });
+}

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/providers/github-copilot-auth.js

@@ -1,5 +1,5 @@
 import { intro, note, outro, spinner } from "@clack/prompts";
-import { ensureAuthProfileStore, upsertAuthProfile } from "../agents/auth-profiles.js";
+import { ensureAuthProfileStore, upsertAuthProfile, } from "../agents/auth-profiles.js";
 import { updateConfig } from "../commands/models/shared.js";
 import { applyAuthProfileConfig } from "../commands/onboard-auth.js";
 import { CONFIG_PATH_NEXUS } from "../config/config.js";