@intent-systems/nexus 2026.1.5-3

package/dist/commands/bootstrap-preset.js

@@ -0,0 +1,214 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { installSkill } from "../agents/skills-install.js";
+import { resolveStateDir } from "../config/paths.js";
+import { NEXUS_ROOT } from "../utils.js";
+const execFileAsync = promisify(execFile);
+function firstName(full) {
+    const trimmed = full.trim();
+    if (!trimmed)
+        return trimmed;
+    return trimmed.split(/\s+/)[0] ?? trimmed;
+}
+function coerceStringArray(input) {
+    if (!Array.isArray(input))
+        return [];
+    return input.map((v) => String(v)).map((s) => s.trim()).filter(Boolean);
+}
+function parseEveWhoamiJson(stdout) {
+    const raw = stdout.trim();
+    if (!raw)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        return {
+            ok: typeof parsed.ok === "boolean" ? parsed.ok : undefined,
+            name: typeof parsed.name === "string" ? parsed.name : undefined,
+            phones: coerceStringArray(parsed.phones),
+            emails: coerceStringArray(parsed.emails),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+async function fileExists(p) {
+    try {
+        await fs.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function hasBin(bin) {
+    try {
+        const res = await execFileAsync("bash", ["-lc", `command -v ${bin}`], {
+            timeout: 5000,
+        });
+        return Boolean(res.stdout.trim());
+    }
+    catch {
+        return false;
+    }
+}
+async function resolveEveCommandPath() {
+    // Prefer PATH
+    if (await hasBin("eve"))
+        return "eve";
+    // Common user-local bin
+    const home = process.env.HOME?.trim();
+    if (home) {
+        const candidate = path.join(home, "bin", "eve");
+        try {
+            await fs.access(candidate);
+            return candidate;
+        }
+        catch {
+            // ignore
+        }
+    }
+    // Developer convenience (Tyler's repo layout)
+    // NOTE: not for general users; used only if present.
+    try {
+        const candidate = path.join(process.env.HOME || "", "nexus", "home", "projects", "eve", "bin", "eve");
+        if (candidate && (await fileExists(candidate)))
+            return candidate;
+    }
+    catch {
+        // ignore
+    }
+    return null;
+}
+function resolvePreset(presetRaw) {
+    const preset = (presetRaw ?? "").trim().toLowerCase();
+    if (preset === "jeeves") {
+        return {
+            agentName: "Jeeves",
+            creature: "Butler",
+            vibe: "helpful, discreet, fast",
+            emoji: "🎩",
+        };
+    }
+    // Default preset: neutral
+    return {
+        agentName: "Nexus bot",
+        creature: "Assistant",
+        vibe: "helpful and concise",
+        emoji: "🧠",
+    };
+}
+export async function applyBootstrapPreset(params) {
+    const { workspaceDir, runtime } = params;
+    const stateDir = resolveStateDir();
+    const agentId = process.env.NEXUS_AGENT_ID?.trim() || "default";
+    const agentIdentityDir = path.join(stateDir, "agents", agentId, "identity");
+    const userIdentityDir = path.join(stateDir, "user", "identity");
+    const onboardingDir = path.join(stateDir, "nexus", "onboarding");
+    const bootstrapPath = path.join(onboardingDir, "BOOTSTRAP.md");
+    if (!(await fileExists(bootstrapPath)))
+        return;
+    await fs.mkdir(agentIdentityDir, { recursive: true });
+    await fs.mkdir(userIdentityDir, { recursive: true });
+    const identityPath = path.join(agentIdentityDir, "IDENTITY.md");
+    const userPath = path.join(userIdentityDir, "PROFILE.md");
+    const soulPath = path.join(agentIdentityDir, "SOUL.md");
+    const agentsPath = path.join(NEXUS_ROOT, "AGENTS.md");
+    const preset = resolvePreset(params.preset);
+    const agentName = (params.agentName?.trim() || preset.agentName).trim();
+    let userName = params.userName?.trim() || "";
+    let preferredAddress = params.preferredAddress?.trim() || "";
+    let detectedPhones = [];
+    let detectedEmails = [];
+    const useEve = params.useEve !== undefined ? params.useEve : Boolean(params.preset);
+    if (useEve && process.platform === "darwin") {
+        let eveCmd = await resolveEveCommandPath();
+        if (!eveCmd) {
+            runtime.log("Installing Eve CLI (for bootstrap identity)…");
+            const tryInstall = async (installId) => await installSkill({
+                workspaceDir,
+                skillName: "eve",
+                installId,
+                timeoutMs: 15 * 60_000,
+            });
+            const installBrew = await tryInstall("brew");
+            if (!installBrew.ok) {
+                runtime.log(`Eve install (brew) failed (${installBrew.message}); trying go install…`);
+                const installGo = await tryInstall("go");
+                if (!installGo.ok) {
+                    runtime.log(`Eve install (go) failed (${installGo.message}); continuing without Eve.`);
+                }
+            }
+            eveCmd = await resolveEveCommandPath();
+        }
+        if (eveCmd) {
+            try {
+                await execFileAsync(eveCmd, ["init"], { timeout: 60_000 });
+            }
+            catch (err) {
+                runtime.log(`Eve init failed; continuing without Eve identity: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            try {
+                const res = await execFileAsync(eveCmd, ["whoami"], { timeout: 30_000 });
+                const whoami = parseEveWhoamiJson(res.stdout);
+                if (whoami?.name)
+                    userName = whoami.name;
+                detectedPhones = whoami?.phones ?? [];
+                detectedEmails = whoami?.emails ?? [];
+                if (!preferredAddress && whoami?.name)
+                    preferredAddress = firstName(whoami.name);
+            }
+            catch (err) {
+                runtime.log(`Eve whoami failed; continuing without Eve identity: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    if (!userName)
+        userName = "Test User";
+    if (!preferredAddress)
+        preferredAddress = firstName(userName) || "friend";
+    const identityMd = `# IDENTITY.md - Agent Identity
+
+- Name: ${agentName}
+- Creature: ${preset.creature}
+- Vibe: ${preset.vibe}
+- Emoji: ${preset.emoji}
+`;
+    const userMd = `# PROFILE.md - User Profile
+
+- Name: ${userName}
+- Preferred address: ${preferredAddress}
+- Pronouns (optional):
+- Timezone (optional):
+- Notes:
+${detectedPhones.length ? `\n- Phones: ${detectedPhones.join(", ")}\n` : ""}
+${detectedEmails.length ? `\n- Emails: ${detectedEmails.join(", ")}\n` : ""}
+`;
+    // Keep SOUL.md if user already customized it; otherwise seed a helpful default.
+    const soulExists = await fileExists(soulPath);
+    if (!soulExists) {
+        const soulMd = `# SOUL.md - Persona & Boundaries
+
+- Be concise and direct.
+- Ask clarifying questions when needed.
+- Never send messages to external services without explicit user confirmation.
+`;
+        await fs.writeFile(soulPath, soulMd, "utf-8");
+    }
+    await fs.writeFile(identityPath, identityMd, "utf-8");
+    await fs.writeFile(userPath, userMd, "utf-8");
+    // Annotate AGENTS.md so future agents know Eve can supply identity data.
+    try {
+        const agents = await fs.readFile(agentsPath, "utf-8");
+        if (!agents.includes("## Identity helpers")) {
+            const appendix = `\n\n## Identity helpers\n\n- You can use \`eve whoami\` (macOS) to detect the user's name/phones/emails from Messages.\n- You can use \`imsg\` to list chats/history and send messages (confirm before sending).\n`;
+            await fs.writeFile(agentsPath, `${agents.trimEnd()}${appendix}`, "utf-8");
+        }
+    }
+    catch {
+        // ignore
+    }
+    // Bootstrap prompt remains in state; Nexus will ignore it once identity exists.
+}

package/dist/commands/capabilities.js

@@ -0,0 +1,36 @@
+import { defaultRuntime } from "../runtime.js";
+import { detectCapabilities } from "../capabilities/detector.js";
+const STATUS_ICON = {
+    active: "✅",
+    ready: "⭐",
+    needs_setup: "🔧",
+    needs_install: "📥",
+    unavailable: "⛔",
+    broken: "❌",
+};
+export async function capabilitiesCommand(opts, runtime = defaultRuntime) {
+    const { registry, capabilities, summary } = detectCapabilities();
+    if (opts?.json) {
+        runtime.log(JSON.stringify({
+            platform: `${process.platform}/${process.arch}`,
+            summary,
+            capabilities,
+        }, null, 2));
+        return;
+    }
+    runtime.log(`\nNexus Capabilities (${process.platform}/${process.arch})`);
+    runtime.log("Legend: ✅ active  ⭐ ready  🔧 needs-setup  📥 needs-install  ⛔ unavailable  ❌ broken\n");
+    for (const [category, entries] of Object.entries(registry.categories)) {
+        const categoryCaps = capabilities.filter((cap) => cap.category === category);
+        if (categoryCaps.length === 0)
+            continue;
+        const activeCount = categoryCaps.filter((cap) => cap.status === "active").length;
+        runtime.log(`${category} (${activeCount}/${categoryCaps.length})`);
+        for (const cap of categoryCaps) {
+            const icon = STATUS_ICON[cap.status] ?? "•";
+            const providers = cap.providers.map((p) => p.id).join(", ");
+            runtime.log(`  ${icon} ${cap.id} — ${providers || cap.providersRaw}`);
+        }
+        runtime.log("");
+    }
+}

package/dist/commands/chutes-oauth.js

@@ -0,0 +1,144 @@
+import { randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+import { CHUTES_AUTHORIZE_ENDPOINT, exchangeChutesCodeForTokens, generateChutesPkce, parseOAuthCallbackInput, } from "../agents/chutes-oauth.js";
+function buildAuthorizeUrl(params) {
+    const qs = new URLSearchParams({
+        client_id: params.clientId,
+        redirect_uri: params.redirectUri,
+        response_type: "code",
+        scope: params.scopes.join(" "),
+        state: params.state,
+        code_challenge: params.challenge,
+        code_challenge_method: "S256",
+    });
+    return `${CHUTES_AUTHORIZE_ENDPOINT}?${qs.toString()}`;
+}
+async function waitForLocalCallback(params) {
+    const redirectUrl = new URL(params.redirectUri);
+    if (redirectUrl.protocol !== "http:") {
+        throw new Error(`Chutes OAuth redirect URI must be http:// (got ${params.redirectUri})`);
+    }
+    const hostname = redirectUrl.hostname || "127.0.0.1";
+    const port = redirectUrl.port ? Number.parseInt(redirectUrl.port, 10) : 80;
+    const expectedPath = redirectUrl.pathname || "/";
+    return await new Promise((resolve, reject) => {
+        let timeout = null;
+        const server = createServer((req, res) => {
+            try {
+                const requestUrl = new URL(req.url ?? "/", redirectUrl.origin);
+                if (requestUrl.pathname !== expectedPath) {
+                    res.statusCode = 404;
+                    res.setHeader("Content-Type", "text/plain; charset=utf-8");
+                    res.end("Not found");
+                    return;
+                }
+                const code = requestUrl.searchParams.get("code")?.trim();
+                const state = requestUrl.searchParams.get("state")?.trim();
+                if (!code) {
+                    res.statusCode = 400;
+                    res.setHeader("Content-Type", "text/plain; charset=utf-8");
+                    res.end("Missing code");
+                    return;
+                }
+                if (!state || state !== params.expectedState) {
+                    res.statusCode = 400;
+                    res.setHeader("Content-Type", "text/plain; charset=utf-8");
+                    res.end("Invalid state");
+                    return;
+                }
+                res.statusCode = 200;
+                res.setHeader("Content-Type", "text/html; charset=utf-8");
+                res.end([
+                    "<!doctype html>",
+                    "<html><head><meta charset='utf-8' /></head>",
+                    "<body><h2>Chutes OAuth complete</h2>",
+                    "<p>You can close this window and return to nexus.</p></body></html>",
+                ].join(""));
+                if (timeout)
+                    clearTimeout(timeout);
+                server.close();
+                resolve({ code, state });
+            }
+            catch (err) {
+                if (timeout)
+                    clearTimeout(timeout);
+                server.close();
+                reject(err);
+            }
+        });
+        server.once("error", (err) => {
+            if (timeout)
+                clearTimeout(timeout);
+            server.close();
+            reject(err);
+        });
+        server.listen(port, hostname, () => {
+            params.onProgress?.(`Waiting for OAuth callback on ${redirectUrl.origin}${expectedPath}…`);
+        });
+        timeout = setTimeout(() => {
+            try {
+                server.close();
+            }
+            catch { }
+            reject(new Error("OAuth callback timeout"));
+        }, params.timeoutMs);
+    });
+}
+export async function loginChutes(params) {
+    const createPkce = params.createPkce ?? generateChutesPkce;
+    const createState = params.createState ?? (() => randomBytes(16).toString("hex"));
+    const { verifier, challenge } = createPkce();
+    const state = createState();
+    const timeoutMs = params.timeoutMs ?? 3 * 60 * 1000;
+    const url = buildAuthorizeUrl({
+        clientId: params.app.clientId,
+        redirectUri: params.app.redirectUri,
+        scopes: params.app.scopes,
+        state,
+        challenge,
+    });
+    let codeAndState;
+    if (params.manual) {
+        await params.onAuth({ url });
+        params.onProgress?.("Waiting for redirect URL…");
+        const input = await params.onPrompt({
+            message: "Paste the redirect URL (or authorization code)",
+            placeholder: `${params.app.redirectUri}?code=...&state=...`,
+        });
+        const parsed = parseOAuthCallbackInput(String(input), state);
+        if ("error" in parsed)
+            throw new Error(parsed.error);
+        if (parsed.state !== state)
+            throw new Error("Invalid OAuth state");
+        codeAndState = parsed;
+    }
+    else {
+        const callback = waitForLocalCallback({
+            redirectUri: params.app.redirectUri,
+            expectedState: state,
+            timeoutMs,
+            onProgress: params.onProgress,
+        }).catch(async () => {
+            params.onProgress?.("OAuth callback not detected; paste redirect URL…");
+            const input = await params.onPrompt({
+                message: "Paste the redirect URL (or authorization code)",
+                placeholder: `${params.app.redirectUri}?code=...&state=...`,
+            });
+            const parsed = parseOAuthCallbackInput(String(input), state);
+            if ("error" in parsed)
+                throw new Error(parsed.error);
+            if (parsed.state !== state)
+                throw new Error("Invalid OAuth state");
+            return parsed;
+        });
+        await params.onAuth({ url });
+        codeAndState = await callback;
+    }
+    params.onProgress?.("Exchanging code for tokens…");
+    return await exchangeChutesCodeForTokens({
+        app: params.app,
+        code: codeAndState.code,
+        codeVerifier: verifier,
+        fetchFn: params.fetchFn,
+    });
+}

package/dist/commands/claude-md.js

@@ -0,0 +1,137 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { buildWorkspaceSkillSnapshot, loadWorkspaceSkillEntries, getSkillMetadata } from "../agents/skills.js";
+import { loadConfig } from "../config/config.js";
+import { defaultRuntime } from "../runtime.js";
+/**
+ * Generate CLAUDE.md file with Nexus skills and workspace context.
+ *
+ * This allows Claude Code to understand available Nexus skills and workspace structure.
+ * The CLAUDE.md file includes:
+ * - Workspace information and structure
+ * - All loaded skill documentation
+ * - Skill metadata (requirements, env vars, install instructions)
+ * - Nexus tools and utilities available
+ *
+ * Usage:
+ *   nexus claude-md [--workspace <path>]
+ */
+export async function claudeMdCommand(opts, runtime = defaultRuntime) {
+    const workspaceDir = opts?.workspace?.trim() || path.join(process.env.HOME || "~", "nexus", "home");
+    runtime.log(`Generating CLAUDE.md for workspace: ${workspaceDir}`);
+    // Load config
+    const config = loadConfig();
+    // Build skill snapshot (this gives us the formatted prompt)
+    const snapshot = buildWorkspaceSkillSnapshot(workspaceDir, { config });
+    // Also load skill entries to get metadata
+    const skillEntries = loadWorkspaceSkillEntries(workspaceDir, { config });
+    runtime.log(`Found ${skillEntries.length} skills`);
+    // Build CLAUDE.md content
+    let claudeContent = `# Nexus Workspace Context
+
+This file provides context for Claude Code when working in this Nexus workspace.
+
+**Auto-generated by \`nexus claude-md\`** - To regenerate, run \`nexus claude-md\`
+
+## Workspace Overview
+
+This is a Nexus workspace located at \`${workspaceDir}\`.
+
+Nexus is an AI operating system that provides:
+- Multi-provider messaging integration (WhatsApp, Telegram, Discord, Signal, etc.)
+- Agent runtime with skills and tools
+- Browser automation and canvas control
+- Session management and persistence
+- Control plane abstraction (single-agent and ODU modes)
+
+## Available Skills
+
+You have access to **${skillEntries.length} Nexus skills**. Each skill provides specialized functionality that can be invoked by the Nexus agent.
+
+### Skill Summary
+
+`;
+    // Add skill metadata
+    for (const entry of skillEntries) {
+        const metadata = getSkillMetadata(entry);
+        const skillName = entry.skill.name;
+        claudeContent += `#### ${skillName}\n\n`;
+        if (metadata) {
+            if (metadata.os && metadata.os.length > 0) {
+                claudeContent += `- **OS compatibility:** ${metadata.os.join(", ")}\n`;
+            }
+            if (metadata.requires?.bins && metadata.requires.bins.length > 0) {
+                claudeContent += `- **Required binaries:** \`${metadata.requires.bins.join("`, `")}\`\n`;
+            }
+            if (metadata.requires?.env && metadata.requires.env.length > 0) {
+                claudeContent += `- **Required environment variables:** \`${metadata.requires.env.join("`, `")}\`\n`;
+            }
+            if (metadata.primaryEnv) {
+                claudeContent += `- **Primary environment variable:** \`${metadata.primaryEnv}\`\n`;
+            }
+            if (metadata.homepage) {
+                claudeContent += `- **Documentation:** ${metadata.homepage}\n`;
+            }
+        }
+        claudeContent += `\n`;
+    }
+    // Add the full formatted skills documentation
+    claudeContent += `## Complete Skills Documentation
+
+The following is the complete documentation for all loaded skills, formatted exactly as the Nexus agent receives it at runtime:
+
+\`\`\`markdown
+${snapshot.prompt}
+\`\`\`
+
+## Nexus Tools
+
+The Nexus agent has access to various tools beyond skills:
+
+- **Browser control:** Automated browser interaction via Playwright
+- **Canvas host:** Screen/camera capture and manipulation
+- **Session management:** Persistent conversation history across providers
+- **Workspace management:** Isolated project environments
+- **Cron scheduling:** Automated task execution
+- **Gateway routing:** Multi-provider message routing and control
+
+## Working with This Workspace
+
+When coding in this workspace:
+
+1. **Use skills:** Reference the skills documentation above to understand available functionality
+2. **Check metadata:** Verify OS/binary/env requirements before using a skill
+3. **Test locally:** Skills run in the Nexus agent runtime with these exact capabilities
+4. **Workspace structure:**
+   - \`${workspaceDir}/\` - Main workspace directory
+   - \`~/nexus/state/\` - Nexus state directory (sessions, logs, config)
+   - \`~/nexus/state/nexus.json\` - Nexus configuration file
+
+## Configuration
+
+To modify Nexus behavior, edit \`~/nexus/state/nexus.json\`.
+
+Key configuration options:
+- \`agent.thinkingDefault\` - Default thinking level ("low", "medium", "high")
+- \`agent.verboseDefault\` - Default verbose mode (boolean)
+- \`agent.timeoutSeconds\` - Agent timeout in seconds
+- \`controlPlane.mode\` - Control plane mode ("single" or "odu")
+
+## Additional Resources
+
+- Run \`nexus doctor\` to verify your Nexus installation
+- Run \`nexus --help\` to see all available CLI commands
+- Check \`~/nexus/state/logs/\` for Nexus logs
+
+---
+
+*This file was auto-generated on ${new Date().toISOString()}*
+`;
+    // Write CLAUDE.md file
+    const claudeMdPath = path.join(workspaceDir, "CLAUDE.md");
+    await fs.writeFile(claudeMdPath, claudeContent, "utf-8");
+    runtime.log(`✓ Generated CLAUDE.md`);
+    runtime.log(`  Path: ${claudeMdPath}`);
+    runtime.log(`  Skills included: ${skillEntries.length}`);
+    runtime.log(`\nClaude Code will now understand your Nexus workspace!`);
+}

package/dist/commands/config-view.js

@@ -0,0 +1,11 @@
+import { defaultRuntime } from "../runtime.js";
+import { readConfigFileSnapshot } from "../config/config.js";
+export async function configViewCommand(opts, runtime = defaultRuntime) {
+    const snapshot = await readConfigFileSnapshot();
+    if (opts?.json) {
+        runtime.log(JSON.stringify(snapshot, null, 2));
+        return;
+    }
+    runtime.log(`Config path: ${snapshot.path}`);
+    runtime.log(`Exists: ${snapshot.exists ? "yes" : "no"}`);
+}