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

package/dist/pairing/pairing-store.js

@@ -0,0 +1,194 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { resolveOAuthDir, resolveStateDir } from "../config/paths.js";
+function resolveCredentialsDir(env = process.env) {
+    const stateDir = resolveStateDir(env, os.homedir);
+    return resolveOAuthDir(env, stateDir);
+}
+function resolvePairingPath(provider, env = process.env) {
+    return path.join(resolveCredentialsDir(env), `${provider}-pairing.json`);
+}
+function resolveAllowFromPath(provider, env = process.env) {
+    return path.join(resolveCredentialsDir(env), `${provider}-allowFrom.json`);
+}
+function safeParseJson(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+async function readJsonFile(filePath, fallback) {
+    try {
+        const raw = await fs.promises.readFile(filePath, "utf-8");
+        const parsed = safeParseJson(raw);
+        if (parsed == null)
+            return { value: fallback, exists: true };
+        return { value: parsed, exists: true };
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return { value: fallback, exists: false };
+        return { value: fallback, exists: false };
+    }
+}
+async function writeJsonFile(filePath, value) {
+    await fs.promises.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.promises.writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf-8");
+}
+function randomCode() {
+    // Human-friendly: 8 chars, upper, no ambiguous chars (0O1I).
+    const alphabet = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
+    let out = "";
+    for (let i = 0; i < 8; i++) {
+        out += alphabet[Math.floor(Math.random() * alphabet.length)];
+    }
+    return out;
+}
+function normalizeId(value) {
+    return String(value).trim();
+}
+function normalizeAllowEntry(provider, entry) {
+    const trimmed = entry.trim();
+    if (!trimmed)
+        return "";
+    if (trimmed === "*")
+        return "";
+    if (provider === "telegram")
+        return trimmed.replace(/^(telegram|tg):/i, "");
+    if (provider === "signal")
+        return trimmed.replace(/^signal:/i, "");
+    if (provider === "discord")
+        return trimmed.replace(/^(discord|user):/i, "");
+    if (provider === "slack")
+        return trimmed.replace(/^(slack|user):/i, "");
+    return trimmed;
+}
+export async function readProviderAllowFromStore(provider, env = process.env) {
+    const filePath = resolveAllowFromPath(provider, env);
+    const { value } = await readJsonFile(filePath, {
+        version: 1,
+        allowFrom: [],
+    });
+    const list = Array.isArray(value.allowFrom) ? value.allowFrom : [];
+    return list
+        .map((v) => normalizeAllowEntry(provider, String(v)))
+        .filter(Boolean);
+}
+export async function addProviderAllowFromStoreEntry(params) {
+    const env = params.env ?? process.env;
+    const filePath = resolveAllowFromPath(params.provider, env);
+    const { value } = await readJsonFile(filePath, {
+        version: 1,
+        allowFrom: [],
+    });
+    const current = (Array.isArray(value.allowFrom) ? value.allowFrom : [])
+        .map((v) => normalizeAllowEntry(params.provider, String(v)))
+        .filter(Boolean);
+    const normalized = normalizeAllowEntry(params.provider, normalizeId(params.entry));
+    if (!normalized)
+        return { changed: false, allowFrom: current };
+    if (current.includes(normalized))
+        return { changed: false, allowFrom: current };
+    const next = [...current, normalized];
+    await writeJsonFile(filePath, {
+        version: 1,
+        allowFrom: next,
+    });
+    return { changed: true, allowFrom: next };
+}
+export async function listProviderPairingRequests(provider, env = process.env) {
+    const filePath = resolvePairingPath(provider, env);
+    const { value } = await readJsonFile(filePath, {
+        version: 1,
+        requests: [],
+    });
+    const reqs = Array.isArray(value.requests) ? value.requests : [];
+    return reqs
+        .filter((r) => r &&
+        typeof r.id === "string" &&
+        typeof r.code === "string" &&
+        typeof r.createdAt === "string")
+        .slice()
+        .sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+}
+export async function upsertProviderPairingRequest(params) {
+    const env = params.env ?? process.env;
+    const filePath = resolvePairingPath(params.provider, env);
+    const { value } = await readJsonFile(filePath, {
+        version: 1,
+        requests: [],
+    });
+    const now = new Date().toISOString();
+    const id = normalizeId(params.id);
+    const meta = params.meta && typeof params.meta === "object"
+        ? Object.fromEntries(Object.entries(params.meta)
+            .map(([k, v]) => [k, String(v ?? "").trim()])
+            .filter(([_, v]) => Boolean(v)))
+        : undefined;
+    const reqs = Array.isArray(value.requests) ? value.requests : [];
+    const existingIdx = reqs.findIndex((r) => r.id === id);
+    if (existingIdx >= 0) {
+        const existing = reqs[existingIdx];
+        const existingCode = existing && typeof existing.code === "string" ? existing.code.trim() : "";
+        const code = existingCode || randomCode();
+        const next = {
+            id,
+            code,
+            createdAt: existing?.createdAt ?? now,
+            lastSeenAt: now,
+            meta: meta ?? existing?.meta,
+        };
+        reqs[existingIdx] = next;
+        await writeJsonFile(filePath, {
+            version: 1,
+            requests: reqs,
+        });
+        return { code, created: false };
+    }
+    const code = randomCode();
+    const next = {
+        id,
+        code,
+        createdAt: now,
+        lastSeenAt: now,
+        ...(meta ? { meta } : {}),
+    };
+    await writeJsonFile(filePath, {
+        version: 1,
+        requests: [...reqs, next],
+    });
+    return { code, created: true };
+}
+export async function approveProviderPairingCode(params) {
+    const env = params.env ?? process.env;
+    const code = params.code.trim().toUpperCase();
+    if (!code)
+        return null;
+    const filePath = resolvePairingPath(params.provider, env);
+    const { value } = await readJsonFile(filePath, {
+        version: 1,
+        requests: [],
+    });
+    const reqs = Array.isArray(value.requests) ? value.requests : [];
+    const idx = reqs.findIndex((r) => String(r.code ?? "").toUpperCase() === code);
+    if (idx < 0)
+        return null;
+    const entry = reqs[idx];
+    if (!entry)
+        return null;
+    reqs.splice(idx, 1);
+    await writeJsonFile(filePath, {
+        version: 1,
+        requests: reqs,
+    });
+    await addProviderAllowFromStoreEntry({
+        provider: params.provider,
+        entry: entry.id,
+        env,
+    });
+    return { id: entry.id, entry };
+}

package/dist/plugins/cli.js

@@ -0,0 +1,42 @@
+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 registerPluginCliCommands(program, cfg) {
+    const config = cfg ?? loadConfig();
+    const workspaceDir = resolveAgentWorkspaceDir(config, resolveDefaultAgentId(config));
+    const logger = {
+        info: (msg) => log.info(msg),
+        warn: (msg) => log.warn(msg),
+        error: (msg) => log.error(msg),
+        debug: (msg) => log.debug(msg),
+    };
+    const registry = loadNexusPlugins({
+        config,
+        workspaceDir,
+        logger,
+    });
+    for (const entry of registry.cliRegistrars) {
+        try {
+            const result = entry.register({
+                program,
+                config,
+                workspaceDir,
+                logger,
+            });
+            if (result && typeof result.then === "function") {
+                void result.catch((err) => {
+                    log.warn(`plugin CLI register failed (${entry.pluginId}): ${String(err)}`);
+                });
+            }
+        }
+        catch (err) {
+            log.warn(`plugin CLI register failed (${entry.pluginId}): ${String(err)}`);
+        }
+    }
+}

package/dist/plugins/discovery.js

@@ -0,0 +1,253 @@
+import fs from "node:fs";
+import path from "node:path";
+import { CONFIG_DIR, resolveUserPath } from "../utils.js";
+const EXTENSION_EXTS = new Set([".ts", ".js", ".mts", ".cts", ".mjs", ".cjs"]);
+function isExtensionFile(filePath) {
+    const ext = path.extname(filePath);
+    if (!EXTENSION_EXTS.has(ext))
+        return false;
+    return !filePath.endsWith(".d.ts");
+}
+function readPackageManifest(dir) {
+    const manifestPath = path.join(dir, "package.json");
+    if (!fs.existsSync(manifestPath))
+        return null;
+    try {
+        const raw = fs.readFileSync(manifestPath, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function resolvePackageExtensions(manifest) {
+    // Try nexus first, fall back to clawdbot for backward compat
+    const raw = manifest.nexus?.extensions ?? manifest.clawdbot?.extensions;
+    if (!Array.isArray(raw))
+        return [];
+    return raw
+        .map((entry) => (typeof entry === "string" ? entry.trim() : ""))
+        .filter(Boolean);
+}
+function deriveIdHint(params) {
+    const base = path.basename(params.filePath, path.extname(params.filePath));
+    const rawPackageName = params.packageName?.trim();
+    if (!rawPackageName)
+        return base;
+    // Prefer the unscoped name so config keys stay stable even when the npm
+    // package is scoped (example: @nexus/voice-call -> voice-call).
+    const unscoped = rawPackageName.includes("/")
+        ? (rawPackageName.split("/").pop() ?? rawPackageName)
+        : rawPackageName;
+    if (!params.hasMultipleExtensions)
+        return unscoped;
+    return `${unscoped}/${base}`;
+}
+function addCandidate(params) {
+    const resolved = path.resolve(params.source);
+    if (params.seen.has(resolved))
+        return;
+    params.seen.add(resolved);
+    const manifest = params.manifest ?? null;
+    params.candidates.push({
+        idHint: params.idHint,
+        source: resolved,
+        origin: params.origin,
+        workspaceDir: params.workspaceDir,
+        packageName: manifest?.name?.trim() || undefined,
+        packageVersion: manifest?.version?.trim() || undefined,
+        packageDescription: manifest?.description?.trim() || undefined,
+    });
+}
+function discoverInDirectory(params) {
+    if (!fs.existsSync(params.dir))
+        return;
+    let entries = [];
+    try {
+        entries = fs.readdirSync(params.dir, { withFileTypes: true });
+    }
+    catch (err) {
+        params.diagnostics.push({
+            level: "warn",
+            message: `failed to read extensions dir: ${params.dir} (${String(err)})`,
+            source: params.dir,
+        });
+        return;
+    }
+    for (const entry of entries) {
+        const fullPath = path.join(params.dir, entry.name);
+        if (entry.isFile()) {
+            if (!isExtensionFile(fullPath))
+                continue;
+            addCandidate({
+                candidates: params.candidates,
+                seen: params.seen,
+                idHint: path.basename(entry.name, path.extname(entry.name)),
+                source: fullPath,
+                origin: params.origin,
+                workspaceDir: params.workspaceDir,
+            });
+        }
+        if (!entry.isDirectory())
+            continue;
+        const manifest = readPackageManifest(fullPath);
+        const extensions = manifest ? resolvePackageExtensions(manifest) : [];
+        if (extensions.length > 0) {
+            for (const extPath of extensions) {
+                const resolved = path.resolve(fullPath, extPath);
+                addCandidate({
+                    candidates: params.candidates,
+                    seen: params.seen,
+                    idHint: deriveIdHint({
+                        filePath: resolved,
+                        packageName: manifest?.name,
+                        hasMultipleExtensions: extensions.length > 1,
+                    }),
+                    source: resolved,
+                    origin: params.origin,
+                    workspaceDir: params.workspaceDir,
+                    manifest,
+                });
+            }
+            continue;
+        }
+        const indexCandidates = ["index.ts", "index.js", "index.mjs", "index.cjs"];
+        const indexFile = indexCandidates
+            .map((candidate) => path.join(fullPath, candidate))
+            .find((candidate) => fs.existsSync(candidate));
+        if (indexFile && isExtensionFile(indexFile)) {
+            addCandidate({
+                candidates: params.candidates,
+                seen: params.seen,
+                idHint: entry.name,
+                source: indexFile,
+                origin: params.origin,
+                workspaceDir: params.workspaceDir,
+            });
+        }
+    }
+}
+function discoverFromPath(params) {
+    const resolved = resolveUserPath(params.rawPath);
+    if (!fs.existsSync(resolved)) {
+        params.diagnostics.push({
+            level: "warn",
+            message: `plugin path not found: ${resolved}`,
+            source: resolved,
+        });
+        return;
+    }
+    const stat = fs.statSync(resolved);
+    if (stat.isFile()) {
+        if (!isExtensionFile(resolved)) {
+            params.diagnostics.push({
+                level: "warn",
+                message: `plugin path is not a supported file: ${resolved}`,
+                source: resolved,
+            });
+            return;
+        }
+        addCandidate({
+            candidates: params.candidates,
+            seen: params.seen,
+            idHint: path.basename(resolved, path.extname(resolved)),
+            source: resolved,
+            origin: params.origin,
+            workspaceDir: params.workspaceDir,
+        });
+        return;
+    }
+    if (stat.isDirectory()) {
+        const manifest = readPackageManifest(resolved);
+        const extensions = manifest ? resolvePackageExtensions(manifest) : [];
+        if (extensions.length > 0) {
+            for (const extPath of extensions) {
+                const source = path.resolve(resolved, extPath);
+                addCandidate({
+                    candidates: params.candidates,
+                    seen: params.seen,
+                    idHint: deriveIdHint({
+                        filePath: source,
+                        packageName: manifest?.name,
+                        hasMultipleExtensions: extensions.length > 1,
+                    }),
+                    source,
+                    origin: params.origin,
+                    workspaceDir: params.workspaceDir,
+                    manifest,
+                });
+            }
+            return;
+        }
+        const indexCandidates = ["index.ts", "index.js", "index.mjs", "index.cjs"];
+        const indexFile = indexCandidates
+            .map((candidate) => path.join(resolved, candidate))
+            .find((candidate) => fs.existsSync(candidate));
+        if (indexFile && isExtensionFile(indexFile)) {
+            addCandidate({
+                candidates: params.candidates,
+                seen: params.seen,
+                idHint: path.basename(resolved),
+                source: indexFile,
+                origin: params.origin,
+                workspaceDir: params.workspaceDir,
+            });
+            return;
+        }
+        discoverInDirectory({
+            dir: resolved,
+            origin: params.origin,
+            workspaceDir: params.workspaceDir,
+            candidates: params.candidates,
+            diagnostics: params.diagnostics,
+            seen: params.seen,
+        });
+        return;
+    }
+}
+export function discoverNexusPlugins(params) {
+    const candidates = [];
+    const diagnostics = [];
+    const seen = new Set();
+    const globalDir = path.join(CONFIG_DIR, "extensions");
+    discoverInDirectory({
+        dir: globalDir,
+        origin: "global",
+        candidates,
+        diagnostics,
+        seen,
+    });
+    const workspaceDir = params.workspaceDir?.trim();
+    if (workspaceDir) {
+        const workspaceRoot = resolveUserPath(workspaceDir);
+        // Try .nexus/extensions first, fall back to .clawdbot/extensions
+        const nexusExt = path.join(workspaceRoot, ".nexus", "extensions");
+        const clawdbotExt = path.join(workspaceRoot, ".clawdbot", "extensions");
+        const workspaceExt = fs.existsSync(nexusExt) ? nexusExt : clawdbotExt;
+        discoverInDirectory({
+            dir: workspaceExt,
+            origin: "workspace",
+            workspaceDir: workspaceRoot,
+            candidates,
+            diagnostics,
+            seen,
+        });
+    }
+    const extra = params.extraPaths ?? [];
+    for (const extraPath of extra) {
+        if (typeof extraPath !== "string")
+            continue;
+        const trimmed = extraPath.trim();
+        if (!trimmed)
+            continue;
+        discoverFromPath({
+            rawPath: trimmed,
+            origin: "config",
+            workspaceDir: workspaceDir?.trim() || undefined,
+            candidates,
+            diagnostics,
+            seen,
+        });
+    }
+    return { candidates, diagnostics };
+}

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,
+    });
+}