@intent-systems/nexus 2026.1.5-3

package/dist/commands/health.js

@@ -0,0 +1,112 @@
+import { loadConfig } from "../config/config.js";
+import { loadSessionStore, resolveStorePath } from "../config/sessions.js";
+import { probeDiscord } from "../discord/probe.js";
+import { callGateway } from "../gateway/call.js";
+import { info } from "../globals.js";
+import { probeTelegram } from "../telegram/probe.js";
+import { resolveTelegramToken } from "../telegram/token.js";
+import { resolveWhatsAppAccount } from "../web/accounts.js";
+import { resolveHeartbeatSeconds } from "../web/reconnect.js";
+import { getWebAuthAgeMs, logWebSelfId, webAuthExists, } from "../web/session.js";
+const DEFAULT_TIMEOUT_MS = 10_000;
+export async function getHealthSnapshot(timeoutMs) {
+    const cfg = loadConfig();
+    const account = resolveWhatsAppAccount({ cfg });
+    const linked = await webAuthExists(account.authDir);
+    const authAgeMs = getWebAuthAgeMs(account.authDir);
+    const heartbeatSeconds = resolveHeartbeatSeconds(cfg, undefined);
+    const storePath = resolveStorePath(cfg.session?.store);
+    const store = loadSessionStore(storePath);
+    const sessions = Object.entries(store)
+        .filter(([key]) => key !== "global" && key !== "unknown")
+        .map(([key, entry]) => ({ key, updatedAt: entry?.updatedAt ?? 0 }))
+        .sort((a, b) => b.updatedAt - a.updatedAt);
+    const recent = sessions.slice(0, 5).map((s) => ({
+        key: s.key,
+        updatedAt: s.updatedAt || null,
+        age: s.updatedAt ? Date.now() - s.updatedAt : null,
+    }));
+    const start = Date.now();
+    const cappedTimeout = Math.max(1000, timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    const { token: telegramToken } = resolveTelegramToken(cfg);
+    const telegramConfigured = telegramToken.trim().length > 0;
+    const telegramProxy = cfg.telegram?.proxy;
+    const telegramProbe = telegramConfigured
+        ? await probeTelegram(telegramToken.trim(), cappedTimeout, telegramProxy)
+        : undefined;
+    const discordToken = process.env.DISCORD_BOT_TOKEN ?? cfg.discord?.token ?? "";
+    const discordConfigured = discordToken.trim().length > 0;
+    const discordProbe = discordConfigured
+        ? await probeDiscord(discordToken.trim(), cappedTimeout)
+        : undefined;
+    const summary = {
+        ok: true,
+        ts: Date.now(),
+        durationMs: Date.now() - start,
+        web: { linked, authAgeMs },
+        telegram: { configured: telegramConfigured, probe: telegramProbe },
+        discord: { configured: discordConfigured, probe: discordProbe },
+        heartbeatSeconds,
+        sessions: {
+            path: storePath,
+            count: sessions.length,
+            recent,
+        },
+    };
+    return summary;
+}
+export async function healthCommand(opts, runtime) {
+    // Always query the running gateway; do not open a direct Baileys socket here.
+    const summary = await callGateway({
+        method: "health",
+        timeoutMs: opts.timeoutMs,
+    });
+    // Gateway reachability defines success; provider issues are reported but not fatal here.
+    const fatal = false;
+    if (opts.json) {
+        runtime.log(JSON.stringify(summary, null, 2));
+    }
+    else {
+        runtime.log(summary.web.linked
+            ? `Web: linked (auth age ${summary.web.authAgeMs ? `${Math.round(summary.web.authAgeMs / 60000)}m` : "unknown"})`
+            : "Web: not linked (run nexus login)");
+        if (summary.web.linked) {
+            const cfg = loadConfig();
+            const account = resolveWhatsAppAccount({ cfg });
+            logWebSelfId(account.authDir, runtime, true);
+        }
+        if (summary.web.connect) {
+            const base = summary.web.connect.ok
+                ? info(`Connect: ok (${summary.web.connect.elapsedMs}ms)`)
+                : `Connect: failed (${summary.web.connect.status ?? "unknown"})`;
+            runtime.log(base +
+                (summary.web.connect.error ? ` - ${summary.web.connect.error}` : ""));
+        }
+        const tgLabel = summary.telegram.configured
+            ? summary.telegram.probe?.ok
+                ? info(`Telegram: ok${summary.telegram.probe.bot?.username ? ` (@${summary.telegram.probe.bot.username})` : ""} (${summary.telegram.probe.elapsedMs}ms)` +
+                    (summary.telegram.probe.webhook?.url
+                        ? ` - webhook ${summary.telegram.probe.webhook.url}`
+                        : ""))
+                : `Telegram: failed (${summary.telegram.probe?.status ?? "unknown"})${summary.telegram.probe?.error ? ` - ${summary.telegram.probe.error}` : ""}`
+            : "Telegram: not configured";
+        runtime.log(tgLabel);
+        const discordLabel = summary.discord.configured
+            ? summary.discord.probe?.ok
+                ? info(`Discord: ok${summary.discord.probe.bot?.username ? ` (@${summary.discord.probe.bot.username})` : ""} (${summary.discord.probe.elapsedMs}ms)`)
+                : `Discord: failed (${summary.discord.probe?.status ?? "unknown"})${summary.discord.probe?.error ? ` - ${summary.discord.probe.error}` : ""}`
+            : "Discord: not configured";
+        runtime.log(discordLabel);
+        runtime.log(info(`Heartbeat interval: ${summary.heartbeatSeconds}s`));
+        runtime.log(info(`Session store: ${summary.sessions.path} (${summary.sessions.count} entries)`));
+        if (summary.sessions.recent.length > 0) {
+            runtime.log("Recent sessions:");
+            for (const r of summary.sessions.recent) {
+                runtime.log(`- ${r.key} (${r.updatedAt ? `${Math.round((Date.now() - r.updatedAt) / 60000)}m ago` : "no activity"})`);
+            }
+        }
+    }
+    if (fatal) {
+        runtime.exit(1);
+    }
+}

package/dist/commands/identity.js

@@ -0,0 +1,54 @@
+import fs from "node:fs";
+import path from "node:path";
+import { resolveStateDir } from "../config/paths.js";
+import { defaultRuntime } from "../runtime.js";
+function readField(pathname, label) {
+    try {
+        const raw = fs.readFileSync(pathname, "utf-8");
+        const regex = new RegExp(`^[-*]?\\s*${label}\\s*:\\s*(.+)$`, "im");
+        const match = raw.match(regex);
+        return match?.[1]?.trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function identityCommand(opts, runtime = defaultRuntime) {
+    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 agentIdentityPath = path.join(agentIdentityDir, "IDENTITY.md");
+    const agentSoulPath = path.join(agentIdentityDir, "SOUL.md");
+    const agentMemoryPath = path.join(agentIdentityDir, "MEMORY.md");
+    const userProfilePath = path.join(userIdentityDir, "PROFILE.md");
+    const payload = {
+        agent: {
+            id: agentId,
+            name: readField(agentIdentityPath, "Name"),
+            identityPath: agentIdentityPath,
+            soulPath: agentSoulPath,
+            memoryPath: agentMemoryPath,
+            exists: fs.existsSync(agentIdentityPath),
+        },
+        user: {
+            name: readField(userProfilePath, "Name"),
+            profilePath: userProfilePath,
+            exists: fs.existsSync(userProfilePath),
+        },
+    };
+    if (opts.json) {
+        runtime.log(JSON.stringify(payload, null, 2));
+        return;
+    }
+    if (!opts.target || opts.target === "user") {
+        runtime.log(`User: ${payload.user.name ?? "(unknown)"}`);
+        runtime.log(`  ${payload.user.profilePath}`);
+    }
+    if (!opts.target || opts.target === "agent") {
+        runtime.log(`Agent: ${payload.agent.name ?? "(unknown)"} (${payload.agent.id})`);
+        runtime.log(`  ${payload.agent.identityPath}`);
+        runtime.log(`  ${payload.agent.soulPath}`);
+        runtime.log(`  ${payload.agent.memoryPath}`);
+    }
+}

package/dist/commands/init.js

@@ -0,0 +1,167 @@
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import { ensureAgentWorkspace } from "../agents/workspace.js";
+import { CONFIG_PATH_NEXUS, writeConfigFile } from "../config/config.js";
+import { resolveStateDir } from "../config/paths.js";
+import { defaultRuntime } from "../runtime.js";
+import { NEXUS_ROOT } from "../utils.js";
+import { copyBundledSkills, generateSkillManifest, writeSkillManifest } from "./skills-manifest.js";
+import { writeCursorRules } from "./cursor-rules.js";
+const execFileAsync = promisify(execFile);
+/**
+ * Checks if a directory is already a git repository.
+ */
+async function isGitRepo(dir) {
+    const gitDir = path.join(dir, ".git");
+    try {
+        const stat = await fs.stat(gitDir);
+        return stat.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Initialize a git repository in the given directory if it's not already a git repo.
+ */
+async function initGitRepo(dir, runtime) {
+    const isRepo = await isGitRepo(dir);
+    if (isRepo) {
+        runtime.log(`  - Git repository already initialized`);
+        return;
+    }
+    // Initialize git repo
+    await execFileAsync("git", ["init"], { cwd: dir });
+    runtime.log(`✓ Initialized git repository`);
+    // Create .gitignore
+    const gitignorePath = path.join(dir, ".gitignore");
+    const gitignoreContent = `# Nexus workspace .gitignore
+
+# Node modules (if you add any JavaScript projects)
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Python (if you use Python scripts)
+__pycache__/
+*.py[cod]
+*.so
+.Python
+venv/
+env/
+
+# Editor files
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Personal secrets (be careful!)
+*.key
+*.pem
+*.cert
+
+# Build outputs
+dist/
+build/
+*.log
+`;
+    await fs.writeFile(gitignorePath, gitignoreContent, "utf-8");
+    runtime.log(`✓ Created .gitignore`);
+}
+/**
+ * Creates the Nexus directory structure:
+ * - ~/nexus/ (root with AGENTS.md and .cursor/rules)
+ * - ~/nexus/home/ (user workspace)
+ * - ~/nexus/state/ (state directory)
+ */
+export async function initCommand(opts, runtime = defaultRuntime) {
+    const workspaceDir = opts?.workspace?.trim() || path.join(process.env.HOME || "~", "nexus", "home");
+    // 1. Create workspace directory and Nexus state scaffolding
+    const workspace = await ensureAgentWorkspace({
+        dir: workspaceDir,
+        ensureBootstrapFiles: true,
+    });
+    runtime.log(`✓ Created workspace: ${workspace.dir}`);
+    if (workspace.agentsPath)
+        runtime.log(`  - ${path.basename(workspace.agentsPath)}`);
+    if (workspace.toolsPath)
+        runtime.log(`  - ${path.basename(workspace.toolsPath)}`);
+    if (workspace.bootstrapPath)
+        runtime.log(`  - ${path.basename(workspace.bootstrapPath)}`);
+    // 2. Create user skills/ directory (for personal custom skills)
+    const userSkillsDir = path.join(workspace.dir, "skills");
+    await fs.mkdir(userSkillsDir, { recursive: true });
+    runtime.log(`✓ Created user skills directory: ${userSkillsDir}`);
+    // 3. Create memory/ and projects/ directories
+    const memoryDir = path.join(workspace.dir, "memory");
+    await fs.mkdir(memoryDir, { recursive: true });
+    const projectsDir = path.join(workspace.dir, "projects");
+    await fs.mkdir(projectsDir, { recursive: true });
+    runtime.log(`✓ Created memory directory: ${memoryDir}`);
+    runtime.log(`✓ Created projects directory: ${projectsDir}`);
+    // 4. Create state directory (~/nexus/state)
+    const stateDir = resolveStateDir();
+    await fs.mkdir(stateDir, { recursive: true });
+    runtime.log(`✓ Created state directory: ${stateDir}`);
+    // 5. Create Nexus workspace metadata + base config file
+    const nexusStateDir = path.join(stateDir, "nexus");
+    await fs.mkdir(nexusStateDir, { recursive: true });
+    try {
+        await fs.access(CONFIG_PATH_NEXUS);
+    }
+    catch {
+        await writeConfigFile({});
+        runtime.log(`✓ Created config file: ${CONFIG_PATH_NEXUS}`);
+    }
+    const workspaceMetaPath = path.join(nexusStateDir, "workspace.json");
+    const workspaceMeta = {
+        version: 1,
+        os: process.platform,
+        arch: process.arch,
+        createdAt: new Date().toISOString(),
+    };
+    await fs.writeFile(workspaceMetaPath, JSON.stringify(workspaceMeta, null, 2), "utf-8");
+    runtime.log(`✓ Created workspace metadata: ${workspaceMetaPath}`);
+    // 6. Create main skills directory (~/nexus/skills) and copy bundled skills
+    const skillsDir = path.join(NEXUS_ROOT, "skills");
+    await fs.mkdir(skillsDir, { recursive: true });
+    runtime.log(`✓ Created skills directory: ${skillsDir}`);
+    // Copy bundled skills from installed package to ~/nexus/skills/
+    const copyResult = await copyBundledSkills(skillsDir);
+    if (copyResult.copied.length > 0) {
+        runtime.log(`✓ Installed ${copyResult.copied.length} bundled skills`);
+    }
+    if (copyResult.skipped.length > 0) {
+        runtime.log(`  - ${copyResult.skipped.length} skills already present`);
+    }
+    if (copyResult.errors.length > 0) {
+        for (const err of copyResult.errors) {
+            runtime.log(`  ⚠ ${err}`);
+        }
+    }
+    // 7. Generate and save skill manifest
+    const manifest = await generateSkillManifest(skillsDir, userSkillsDir);
+    await writeSkillManifest(manifest);
+    runtime.log(`✓ Created skills manifest (${manifest.bundled.count} bundled, ${manifest.user.count} user)`);
+    // 8. Write .cursor/rules at workspace root
+    const cursorRulesPath = await writeCursorRules({
+        workspaceDir: NEXUS_ROOT,
+        outputPath: path.join(NEXUS_ROOT, ".cursor", "rules"),
+        includeAgentsMd: true,
+        includeBootstrap: false,
+    });
+    runtime.log(`✓ Created Cursor rules: ${cursorRulesPath}`);
+    // 9. Initialize git repository for workspace
+    await initGitRepo(workspace.dir, runtime);
+    runtime.log("\nNexus initialization complete!");
+    runtime.log(`\nNext steps:\n  - Run 'nexus status' to orient\n  - Open ${NEXUS_ROOT} in your editor`);
+}

package/dist/commands/models/aliases.js

@@ -0,0 +1,85 @@
+import { CONFIG_PATH_NEXUS, loadConfig } from "../../config/config.js";
+import { ensureFlagCompatibility, normalizeAlias, resolveModelTarget, updateConfig, } from "./shared.js";
+export async function modelsAliasesListCommand(opts, runtime) {
+    ensureFlagCompatibility(opts);
+    const cfg = loadConfig();
+    const models = cfg.agent?.models ?? {};
+    const aliases = Object.entries(models).reduce((acc, [modelKey, entry]) => {
+        const alias = entry?.alias?.trim();
+        if (alias)
+            acc[alias] = modelKey;
+        return acc;
+    }, {});
+    if (opts.json) {
+        runtime.log(JSON.stringify({ aliases }, null, 2));
+        return;
+    }
+    if (opts.plain) {
+        for (const [alias, target] of Object.entries(aliases)) {
+            runtime.log(`${alias} ${target}`);
+        }
+        return;
+    }
+    runtime.log(`Aliases (${Object.keys(aliases).length}):`);
+    if (Object.keys(aliases).length === 0) {
+        runtime.log("- none");
+        return;
+    }
+    for (const [alias, target] of Object.entries(aliases)) {
+        runtime.log(`- ${alias} -> ${target}`);
+    }
+}
+export async function modelsAliasesAddCommand(aliasRaw, modelRaw, runtime) {
+    const alias = normalizeAlias(aliasRaw);
+    const resolved = resolveModelTarget({ raw: modelRaw, cfg: loadConfig() });
+    const _updated = await updateConfig((cfg) => {
+        const modelKey = `${resolved.provider}/${resolved.model}`;
+        const nextModels = { ...cfg.agent?.models };
+        for (const [key, entry] of Object.entries(nextModels)) {
+            const existing = entry?.alias?.trim();
+            if (existing && existing === alias && key !== modelKey) {
+                throw new Error(`Alias ${alias} already points to ${key}.`);
+            }
+        }
+        const existing = nextModels[modelKey] ?? {};
+        nextModels[modelKey] = { ...existing, alias };
+        return {
+            ...cfg,
+            agent: {
+                ...cfg.agent,
+                models: nextModels,
+            },
+        };
+    });
+    runtime.log(`Updated ${CONFIG_PATH_NEXUS}`);
+    runtime.log(`Alias ${alias} -> ${resolved.provider}/${resolved.model}`);
+}
+export async function modelsAliasesRemoveCommand(aliasRaw, runtime) {
+    const alias = normalizeAlias(aliasRaw);
+    const updated = await updateConfig((cfg) => {
+        const nextModels = { ...cfg.agent?.models };
+        let found = false;
+        for (const [key, entry] of Object.entries(nextModels)) {
+            if (entry?.alias?.trim() === alias) {
+                nextModels[key] = { ...entry, alias: undefined };
+                found = true;
+                break;
+            }
+        }
+        if (!found) {
+            throw new Error(`Alias not found: ${alias}`);
+        }
+        return {
+            ...cfg,
+            agent: {
+                ...cfg.agent,
+                models: nextModels,
+            },
+        };
+    });
+    runtime.log(`Updated ${CONFIG_PATH_NEXUS}`);
+    if (!updated.agent?.models ||
+        Object.values(updated.agent.models).every((entry) => !entry?.alias?.trim())) {
+        runtime.log("No aliases configured.");
+    }
+}

package/dist/commands/models/fallbacks.js

@@ -0,0 +1,123 @@
+import { buildModelAliasIndex, resolveModelRefFromString } from "../../agents/model-selection.js";
+import { CONFIG_PATH_NEXUS, loadConfig } from "../../config/config.js";
+import { DEFAULT_PROVIDER, ensureFlagCompatibility, modelKey, resolveModelTarget, updateConfig, } from "./shared.js";
+export async function modelsFallbacksListCommand(opts, runtime) {
+    ensureFlagCompatibility(opts);
+    const cfg = loadConfig();
+    const fallbacks = cfg.agent?.model?.fallbacks ?? [];
+    if (opts.json) {
+        runtime.log(JSON.stringify({ fallbacks }, null, 2));
+        return;
+    }
+    if (opts.plain) {
+        for (const entry of fallbacks)
+            runtime.log(entry);
+        return;
+    }
+    runtime.log(`Fallbacks (${fallbacks.length}):`);
+    if (fallbacks.length === 0) {
+        runtime.log("- none");
+        return;
+    }
+    for (const entry of fallbacks)
+        runtime.log(`- ${entry}`);
+}
+export async function modelsFallbacksAddCommand(modelRaw, runtime) {
+    const updated = await updateConfig((cfg) => {
+        const resolved = resolveModelTarget({ raw: modelRaw, cfg });
+        const targetKey = modelKey(resolved.provider, resolved.model);
+        const nextModels = { ...cfg.agent?.models };
+        if (!nextModels[targetKey])
+            nextModels[targetKey] = {};
+        const aliasIndex = buildModelAliasIndex({
+            cfg,
+            defaultProvider: DEFAULT_PROVIDER,
+        });
+        const existing = cfg.agent?.model?.fallbacks ?? [];
+        const existingKeys = existing
+            .map((entry) => resolveModelRefFromString({
+            raw: String(entry ?? ""),
+            defaultProvider: DEFAULT_PROVIDER,
+            aliasIndex,
+        }))
+            .filter((entry) => Boolean(entry))
+            .map((entry) => modelKey(entry.ref.provider, entry.ref.model));
+        if (existingKeys.includes(targetKey))
+            return cfg;
+        const existingModel = cfg.agent?.model;
+        return {
+            ...cfg,
+            agent: {
+                ...cfg.agent,
+                model: {
+                    ...(existingModel?.primary
+                        ? { primary: existingModel.primary }
+                        : undefined),
+                    fallbacks: [...existing, targetKey],
+                },
+                models: nextModels,
+            },
+        };
+    });
+    runtime.log(`Updated ${CONFIG_PATH_NEXUS}`);
+    runtime.log(`Fallbacks: ${(updated.agent?.model?.fallbacks ?? []).join(", ")}`);
+}
+export async function modelsFallbacksRemoveCommand(modelRaw, runtime) {
+    const updated = await updateConfig((cfg) => {
+        const resolved = resolveModelTarget({ raw: modelRaw, cfg });
+        const targetKey = modelKey(resolved.provider, resolved.model);
+        const aliasIndex = buildModelAliasIndex({
+            cfg,
+            defaultProvider: DEFAULT_PROVIDER,
+        });
+        const existing = cfg.agent?.model?.fallbacks ?? [];
+        const filtered = existing.filter((entry) => {
+            const resolvedEntry = resolveModelRefFromString({
+                raw: String(entry ?? ""),
+                defaultProvider: DEFAULT_PROVIDER,
+                aliasIndex,
+            });
+            if (!resolvedEntry)
+                return true;
+            return (modelKey(resolvedEntry.ref.provider, resolvedEntry.ref.model) !==
+                targetKey);
+        });
+        if (filtered.length === existing.length) {
+            throw new Error(`Fallback not found: ${targetKey}`);
+        }
+        const existingModel = cfg.agent?.model;
+        return {
+            ...cfg,
+            agent: {
+                ...cfg.agent,
+                model: {
+                    ...(existingModel?.primary
+                        ? { primary: existingModel.primary }
+                        : undefined),
+                    fallbacks: filtered,
+                },
+            },
+        };
+    });
+    runtime.log(`Updated ${CONFIG_PATH_NEXUS}`);
+    runtime.log(`Fallbacks: ${(updated.agent?.model?.fallbacks ?? []).join(", ")}`);
+}
+export async function modelsFallbacksClearCommand(runtime) {
+    await updateConfig((cfg) => {
+        const existingModel = cfg.agent?.model;
+        return {
+            ...cfg,
+            agent: {
+                ...cfg.agent,
+                model: {
+                    ...(existingModel?.primary
+                        ? { primary: existingModel.primary }
+                        : undefined),
+                    fallbacks: [],
+                },
+            },
+        };
+    });
+    runtime.log(`Updated ${CONFIG_PATH_NEXUS}`);
+    runtime.log("Fallback list cleared.");
+}

package/dist/commands/models/image-fallbacks.js

@@ -0,0 +1,123 @@
+import { buildModelAliasIndex, resolveModelRefFromString } from "../../agents/model-selection.js";
+import { CONFIG_PATH_NEXUS, loadConfig } from "../../config/config.js";
+import { DEFAULT_PROVIDER, ensureFlagCompatibility, modelKey, resolveModelTarget, updateConfig, } from "./shared.js";
+export async function modelsImageFallbacksListCommand(opts, runtime) {
+    ensureFlagCompatibility(opts);
+    const cfg = loadConfig();
+    const fallbacks = cfg.agent?.imageModel?.fallbacks ?? [];
+    if (opts.json) {
+        runtime.log(JSON.stringify({ fallbacks }, null, 2));
+        return;
+    }
+    if (opts.plain) {
+        for (const entry of fallbacks)
+            runtime.log(entry);
+        return;
+    }
+    runtime.log(`Image fallbacks (${fallbacks.length}):`);
+    if (fallbacks.length === 0) {
+        runtime.log("- none");
+        return;
+    }
+    for (const entry of fallbacks)
+        runtime.log(`- ${entry}`);
+}
+export async function modelsImageFallbacksAddCommand(modelRaw, runtime) {
+    const updated = await updateConfig((cfg) => {
+        const resolved = resolveModelTarget({ raw: modelRaw, cfg });
+        const targetKey = modelKey(resolved.provider, resolved.model);
+        const nextModels = { ...cfg.agent?.models };
+        if (!nextModels[targetKey])
+            nextModels[targetKey] = {};
+        const aliasIndex = buildModelAliasIndex({
+            cfg,
+            defaultProvider: DEFAULT_PROVIDER,
+        });
+        const existing = cfg.agent?.imageModel?.fallbacks ?? [];
+        const existingKeys = existing
+            .map((entry) => resolveModelRefFromString({
+            raw: String(entry ?? ""),
+            defaultProvider: DEFAULT_PROVIDER,
+            aliasIndex,
+        }))
+            .filter((entry) => Boolean(entry))
+            .map((entry) => modelKey(entry.ref.provider, entry.ref.model));
+        if (existingKeys.includes(targetKey))
+            return cfg;
+        const existingModel = cfg.agent?.imageModel;
+        return {
+            ...cfg,
+            agent: {
+                ...cfg.agent,
+                imageModel: {
+                    ...(existingModel?.primary
+                        ? { primary: existingModel.primary }
+                        : undefined),
+                    fallbacks: [...existing, targetKey],
+                },
+                models: nextModels,
+            },
+        };
+    });
+    runtime.log(`Updated ${CONFIG_PATH_NEXUS}`);
+    runtime.log(`Image fallbacks: ${(updated.agent?.imageModel?.fallbacks ?? []).join(", ")}`);
+}
+export async function modelsImageFallbacksRemoveCommand(modelRaw, runtime) {
+    const updated = await updateConfig((cfg) => {
+        const resolved = resolveModelTarget({ raw: modelRaw, cfg });
+        const targetKey = modelKey(resolved.provider, resolved.model);
+        const aliasIndex = buildModelAliasIndex({
+            cfg,
+            defaultProvider: DEFAULT_PROVIDER,
+        });
+        const existing = cfg.agent?.imageModel?.fallbacks ?? [];
+        const filtered = existing.filter((entry) => {
+            const resolvedEntry = resolveModelRefFromString({
+                raw: String(entry ?? ""),
+                defaultProvider: DEFAULT_PROVIDER,
+                aliasIndex,
+            });
+            if (!resolvedEntry)
+                return true;
+            return (modelKey(resolvedEntry.ref.provider, resolvedEntry.ref.model) !==
+                targetKey);
+        });
+        if (filtered.length === existing.length) {
+            throw new Error(`Image fallback not found: ${targetKey}`);
+        }
+        const existingModel = cfg.agent?.imageModel;
+        return {
+            ...cfg,
+            agent: {
+                ...cfg.agent,
+                imageModel: {
+                    ...(existingModel?.primary
+                        ? { primary: existingModel.primary }
+                        : undefined),
+                    fallbacks: filtered,
+                },
+            },
+        };
+    });
+    runtime.log(`Updated ${CONFIG_PATH_NEXUS}`);
+    runtime.log(`Image fallbacks: ${(updated.agent?.imageModel?.fallbacks ?? []).join(", ")}`);
+}
+export async function modelsImageFallbacksClearCommand(runtime) {
+    await updateConfig((cfg) => {
+        const existingModel = cfg.agent?.imageModel;
+        return {
+            ...cfg,
+            agent: {
+                ...cfg.agent,
+                imageModel: {
+                    ...(existingModel?.primary
+                        ? { primary: existingModel.primary }
+                        : undefined),
+                    fallbacks: [],
+                },
+            },
+        };
+    });
+    runtime.log(`Updated ${CONFIG_PATH_NEXUS}`);
+    runtime.log("Image fallback list cleared.");
+}