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

package/dist/agents/skills.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { formatSkillsForPrompt, loadSkillsFromDir, } from "@mariozechner/pi-coding-agent";
-import { MANAGED_SKILLS_DIR, resolveUserPath } from "../utils.js";
+import { NEXUS_ROOT, resolveUserPath } from "../utils.js";
 function resolveBundledSkillsDir() {
     const override = process.env.NEXUS_BUNDLED_SKILLS_DIR?.trim();
     if (override)
@@ -41,6 +41,13 @@ function stripQuotes(value) {
     }
     return value;
 }
+function resolveSkillRootDirs(rootDir) {
+    const typedDirs = ["tools", "connectors", "guides"].map((segment) => path.join(rootDir, segment));
+    const existingTyped = typedDirs.filter((dir) => fs.existsSync(dir));
+    if (existingTyped.length > 0)
+        return existingTyped;
+    return fs.existsSync(rootDir) ? [rootDir] : [];
+}
 function parseFrontmatter(content) {
     const frontmatter = {};
     const normalized = content.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
@@ -212,7 +219,9 @@ function resolveNexusMetadata(frontmatter) {
         const requiresRaw = typeof metadataObj.requires === "object" && metadataObj.requires !== null
             ? metadataObj.requires
             : undefined;
-        const installRaw = Array.isArray(metadataObj.install) ? metadataObj.install : [];
+        const installRaw = Array.isArray(metadataObj.install)
+            ? metadataObj.install
+            : [];
         const install = installRaw
             .map((entry) => parseInstallSpec(entry))
             .filter((entry) => Boolean(entry));
@@ -223,11 +232,19 @@ function resolveNexusMetadata(frontmatter) {
             : undefined;
         const provides = normalizeStringList(metadataObj.provides);
         return {
-            always: typeof metadataObj.always === "boolean" ? metadataObj.always : undefined,
+            always: typeof metadataObj.always === "boolean"
+                ? metadataObj.always
+                : undefined,
             emoji: typeof metadataObj.emoji === "string" ? metadataObj.emoji : undefined,
-            homepage: typeof metadataObj.homepage === "string" ? metadataObj.homepage : undefined,
-            skillKey: typeof metadataObj.skillKey === "string" ? metadataObj.skillKey : undefined,
-            primaryEnv: typeof metadataObj.primaryEnv === "string" ? metadataObj.primaryEnv : undefined,
+            homepage: typeof metadataObj.homepage === "string"
+                ? metadataObj.homepage
+                : undefined,
+            skillKey: typeof metadataObj.skillKey === "string"
+                ? metadataObj.skillKey
+                : undefined,
+            primaryEnv: typeof metadataObj.primaryEnv === "string"
+                ? metadataObj.primaryEnv
+                : undefined,
             os: osRaw.length > 0 ? osRaw : undefined,
             type,
             provides: provides.length > 0 ? provides : undefined,
@@ -251,7 +268,7 @@ export function getSkillMetadata(entry) {
     return entry.nexus;
 }
 function resolveSkillKey(skill, entry) {
-    return entry ? getSkillMetadata(entry)?.skillKey ?? skill.name : skill.name;
+    return entry ? (getSkillMetadata(entry)?.skillKey ?? skill.name) : skill.name;
 }
 function shouldIncludeSkill(params) {
     const { entry, config } = params;
@@ -289,7 +306,8 @@ function shouldIncludeSkill(params) {
                 continue;
             if (skillConfig?.env?.[envName])
                 continue;
-            if (skillConfig?.apiKey && getSkillMetadata(entry)?.primaryEnv === envName) {
+            if (skillConfig?.apiKey &&
+                getSkillMetadata(entry)?.primaryEnv === envName) {
                 continue;
             }
             return false;
@@ -387,36 +405,24 @@ function loadSkillEntries(workspaceDir, opts) {
         }
         return [];
     };
-    const managedSkillsDir = opts?.managedSkillsDir ?? MANAGED_SKILLS_DIR;
-    const workspaceSkillsDir = path.join(workspaceDir, "skills");
+    const workspaceSkillsRoot = path.join(NEXUS_ROOT, "skills");
+    const userSkillsRoot = path.join(resolveUserPath(workspaceDir), "skills");
+    const managedSkillsDir = opts?.managedSkillsDir ?? path.join(workspaceSkillsRoot, "managed");
     const bundledSkillsDir = opts?.bundledSkillsDir ?? resolveBundledSkillsDir();
     const extraDirsRaw = opts?.config?.skills?.load?.extraDirs ?? [];
     const extraDirs = extraDirsRaw
         .map((d) => (typeof d === "string" ? d.trim() : ""))
         .filter(Boolean);
+    const loadFromDirs = (dirs, source) => dirs.flatMap((dir) => loadSkills({ dir, source }));
     const bundledSkills = bundledSkillsDir
-        ? loadSkills({
-            dir: bundledSkillsDir,
-            source: "nexus-bundled",
-        })
+        ? loadFromDirs(resolveSkillRootDirs(bundledSkillsDir), "nexus-bundled")
         : [];
-    const extraSkills = extraDirs.flatMap((dir) => {
-        const resolved = resolveUserPath(dir);
-        return loadSkills({
-            dir: resolved,
-            source: "nexus-extra",
-        });
-    });
-    const managedSkills = loadSkills({
-        dir: managedSkillsDir,
-        source: "nexus-managed",
-    });
-    const workspaceSkills = loadSkills({
-        dir: workspaceSkillsDir,
-        source: "nexus-workspace",
-    });
+    const extraSkills = extraDirs.flatMap((dir) => loadFromDirs(resolveSkillRootDirs(resolveUserPath(dir)), "nexus-extra"));
+    const managedSkills = loadFromDirs(resolveSkillRootDirs(managedSkillsDir), "nexus-managed");
+    const workspaceSkills = loadFromDirs(resolveSkillRootDirs(workspaceSkillsRoot), "nexus-workspace");
+    const userSkills = loadFromDirs(resolveSkillRootDirs(userSkillsRoot), "nexus-user");
     const merged = new Map();
-    // Precedence: extra < bundled < managed < workspace
+    // Precedence: extra < bundled < managed < workspace < user
     for (const skill of extraSkills)
         merged.set(skill.name, skill);
     for (const skill of bundledSkills)
@@ -425,6 +431,8 @@ function loadSkillEntries(workspaceDir, opts) {
         merged.set(skill.name, skill);
     for (const skill of workspaceSkills)
         merged.set(skill.name, skill);
+    for (const skill of userSkills)
+        merged.set(skill.name, skill);
     const skillEntries = Array.from(merged.values()).map((skill) => {
         let frontmatter = {};
         try {

package/dist/agents/subagent-registry.js

@@ -2,26 +2,31 @@ import crypto from "node:crypto";
 import { loadConfig, STATE_DIR_NEXUS } from "../config/config.js";
 import { callGateway } from "../gateway/call.js";
 import { normalizeAgentId, parseAgentSessionKey, resolveAgentIdFromSessionKey, } from "../routing/session-key.js";
-import { resolveDisplaySessionKey, resolveInternalSessionKey, resolveMainSessionAlias, stripToolMessages, } from "./tools/sessions-helpers.js";
-import { resolveAnnounceTarget } from "./tools/sessions-announce-target.js";
+import { createFileSubagentStore, } from "./subagent-registry.store.js";
 import { readLatestAssistantReply, runAgentStep } from "./tools/agent-step.js";
+import { resolveAnnounceTarget } from "./tools/sessions-announce-target.js";
+import { resolveDisplaySessionKey, resolveInternalSessionKey, resolveMainSessionAlias, stripToolMessages, } from "./tools/sessions-helpers.js";
 import { isAnnounceSkip } from "./tools/sessions-send-helpers.js";
-import { createFileSubagentStore, } from "./subagent-registry.store.js";
 function normalizeStoredEntry(entry) {
     if (!entry || typeof entry !== "object")
         return null;
     const sessionKey = typeof entry.sessionKey === "string" ? entry.sessionKey.trim() : "";
-    const parentSessionKey = typeof entry.parentSessionKey === "string" ? entry.parentSessionKey.trim() : "";
+    const parentSessionKey = typeof entry.parentSessionKey === "string"
+        ? entry.parentSessionKey.trim()
+        : "";
     if (!sessionKey || !parentSessionKey)
         return null;
-    const status = entry.status === "announced" || entry.status === "failed" || entry.status === "pending"
+    const status = entry.status === "announced" ||
+        entry.status === "failed" ||
+        entry.status === "pending"
         ? entry.status
         : "pending";
     const createdAt = typeof entry.createdAt === "string" && entry.createdAt.trim()
         ? entry.createdAt
         : new Date().toISOString();
     const agentId = normalizeAgentId(entry.agentId);
-    const legacyRequester = entry.requesterProvider;
+    const legacyRequester = entry
+        .requesterProvider;
     return {
         ...entry,
         agentId,
@@ -36,8 +41,12 @@ function buildSubagentAnnouncePrompt(params) {
     const taskLine = params.task?.trim() ? params.task.trim() : "(not available)";
     const lines = [
         "Sub-agent announce step:",
-        params.requesterSessionKey ? `Requester session: ${params.requesterSessionKey}.` : undefined,
-        params.requesterChannel ? `Requester channel: ${params.requesterChannel}.` : undefined,
+        params.requesterSessionKey
+            ? `Requester session: ${params.requesterSessionKey}.`
+            : undefined,
+        params.requesterChannel
+            ? `Requester channel: ${params.requesterChannel}.`
+            : undefined,
         `Post target channel: ${params.announceChannel}.`,
         `Original task: ${taskLine}`,
         params.subagentReply
@@ -94,7 +103,9 @@ async function readSubagentTask(sessionKey) {
 }
 async function runSubagentAnnounceFlow(params) {
     let status = "pending";
-    const timeoutMs = typeof params.timeoutMs === "number" && params.timeoutMs > 0 ? params.timeoutMs : 30_000;
+    const timeoutMs = typeof params.timeoutMs === "number" && params.timeoutMs > 0
+        ? params.timeoutMs
+        : 30_000;
     try {
         let reply = params.roundOneReply?.trim();
         if (!reply) {
@@ -140,7 +151,9 @@ async function runSubagentAnnounceFlow(params) {
             timeoutMs,
             lane: "nested",
         });
-        if (!announceReply || !announceReply.trim() || isAnnounceSkip(announceReply)) {
+        if (!announceReply ||
+            !announceReply.trim() ||
+            isAnnounceSkip(announceReply)) {
             status = "announced";
             return status;
         }
@@ -178,7 +191,8 @@ async function runSubagentAnnounceFlow(params) {
     }
 }
 export function createSubagentRegistry(params) {
-    const store = params?.store ?? createFileSubagentStore(params?.stateDir ?? STATE_DIR_NEXUS);
+    const store = params?.store ??
+        createFileSubagentStore(params?.stateDir ?? STATE_DIR_NEXUS);
     const entries = new Map();
     let initialized = false;
     let resumeInFlight = null;

package/dist/agents/system-prompt.js

@@ -82,6 +82,7 @@ export function buildAgentSystemPromptAppend(params) {
     const userTimezone = params.userTimezone?.trim();
     const userTime = params.userTime?.trim();
     const runtimeInfo = params.runtimeInfo;
+    const reactionGuidance = params.reactionGuidance;
     const runtimeLines = [];
     if (runtimeInfo?.host)
         runtimeLines.push(`Host: ${runtimeInfo.host}`);
@@ -124,6 +125,12 @@ export function buildAgentSystemPromptAppend(params) {
             : "",
         "TOOLS.md does not control tool availability; it is user guidance for how to use external tools.",
         "",
+        "## Nexus CLI Quick Reference",
+        "- nexus status: show overall status",
+        "- nexus gateway restart: restart the gateway process",
+        "- nexus usage upload: upload usage batches",
+        "Do not invent commands; run `nexus help` to list available commands.",
+        "",
         "## Workspace",
         `Your working directory is: ${params.workspaceDir}`,
         "Treat this directory as the single global workspace for file operations unless explicitly instructed otherwise.",
@@ -167,6 +174,15 @@ export function buildAgentSystemPromptAppend(params) {
         "- [[reply_to:<id>]] replies to a specific message id when you have it.",
         "Tags are stripped before sending; support depends on the current provider config.",
         "",
+        reactionGuidance && reactionGuidance.level && reactionGuidance.level !== "off"
+            ? "## Reactions"
+            : "",
+        reactionGuidance && reactionGuidance.level && reactionGuidance.level !== "off"
+            ? `Reactions are enabled for ${reactionGuidance.channel ?? "this channel"} in ${reactionGuidance.level.toUpperCase()} mode.`
+            : "",
+        reactionGuidance && reactionGuidance.level && reactionGuidance.level !== "off"
+            ? ""
+            : "",
     ];
     if (extraSystemPrompt) {
         lines.push("## Group Chat Context", extraSystemPrompt, "");

package/dist/agents/tool-policy.js

@@ -10,7 +10,12 @@ export const TOOL_GROUPS = {
     // Host/runtime execution tools
     "group:runtime": ["exec", "process"],
     // Session management tools
-    "group:sessions": ["sessions_list", "sessions_history", "sessions_send", "sessions_spawn"],
+    "group:sessions": [
+        "sessions_list",
+        "sessions_history",
+        "sessions_send",
+        "sessions_spawn",
+    ],
     // UI helpers
     "group:ui": ["browser", "canvas"],
     // Automation + infra
@@ -43,10 +48,21 @@ const TOOL_PROFILES = {
         allow: ["sessions_list"],
     },
     coding: {
-        allow: ["group:fs", "group:runtime", "group:sessions", "group:memory", "image"],
+        allow: [
+            "group:fs",
+            "group:runtime",
+            "group:sessions",
+            "group:memory",
+            "image",
+        ],
     },
     messaging: {
-        allow: ["group:messaging", "sessions_list", "sessions_history", "sessions_send"],
+        allow: [
+            "group:messaging",
+            "sessions_list",
+            "sessions_history",
+            "sessions_send",
+        ],
     },
     full: {},
 };

package/dist/agents/tools/browser-tool.js

@@ -1,8 +1,8 @@
 import { Type } from "@sinclair/typebox";
 import { browserCloseTab, browserFocusTab, browserOpenTab, browserSnapshot, browserStart, browserStatus, browserStop, browserTabs, } from "../../browser/client.js";
 import { browserAct, browserArmDialog, browserArmFileChooser, browserConsoleMessages, browserNavigate, browserPdfSave, browserScreenshotAction, } from "../../browser/client-actions.js";
-import { DEFAULT_AI_SNAPSHOT_MAX_CHARS } from "../../browser/constants.js";
 import { resolveBrowserConfig } from "../../browser/config.js";
+import { DEFAULT_AI_SNAPSHOT_MAX_CHARS } from "../../browser/constants.js";
 import { loadConfig } from "../../config/config.js";
 import { imageResultFromFile, jsonResult, readStringParam, } from "./common.js";
 const BrowserActSchema = Type.Union([
@@ -178,11 +178,14 @@ export function createBrowserTool(opts) {
                         params.maxChars > 0
                         ? Math.floor(params.maxChars)
                         : undefined;
-                    const resolvedMaxChars = format === "ai" ? maxChars ?? DEFAULT_AI_SNAPSHOT_MAX_CHARS : undefined;
+                    const resolvedMaxChars = format === "ai"
+                        ? (maxChars ?? DEFAULT_AI_SNAPSHOT_MAX_CHARS)
+                        : undefined;
                     const snapshot = await browserSnapshot(baseUrl, {
                         format,
                         targetId,
                         limit,
+                        maxChars: resolvedMaxChars,
                     });
                     if (snapshot.format === "ai") {
                         return {

package/dist/agents/tools/image-tool.js

@@ -1,18 +1,92 @@
 import { complete, } from "@mariozechner/pi-ai";
 import { discoverAuthStorage, discoverModels, } from "@mariozechner/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
+import { listCredentialEntriesSync } from "../../credentials/store.js";
 import { resolveUserPath } from "../../utils.js";
 import { loadWebMedia } from "../../web/media.js";
-import { getApiKeyForModel } from "../model-auth.js";
+import { DEFAULT_PROVIDER } from "../defaults.js";
+import { getApiKeyForModel, getCustomProviderApiKey, resolveEnvApiKey, } from "../model-auth.js";
 import { runWithImageModelFallback } from "../model-fallback.js";
+import { normalizeProviderId, parseModelRef } from "../model-selection.js";
 import { ensureNexusModelsJson } from "../models-config.js";
 import { extractAssistantText } from "../pi-embedded-utils.js";
 const DEFAULT_PROMPT = "Describe the image.";
-function ensureImageToolConfigured(cfg) {
-    const imageModel = cfg?.agent?.imageModel;
-    const primary = typeof imageModel === "string" ? imageModel.trim() : imageModel?.primary;
-    const fallbacks = typeof imageModel === "object" ? (imageModel?.fallbacks ?? []) : [];
-    return Boolean(primary?.trim() || fallbacks.length > 0);
+const DEFAULT_IMAGE_MODELS = {
+    minimax: "minimax-vl-01",
+    openai: "gpt-5-mini",
+    anthropic: "claude-opus-4-5",
+};
+function normalizeImageModelConfig(value) {
+    if (typeof value === "string") {
+        const primary = value.trim();
+        return primary ? { primary } : null;
+    }
+    if (!value || typeof value !== "object")
+        return null;
+    const primary = typeof value.primary === "string" ? value.primary.trim() : "";
+    const fallbacks = Array.isArray(value.fallbacks)
+        ? value.fallbacks.map((raw) => String(raw ?? "").trim()).filter(Boolean)
+        : [];
+    if (!primary && fallbacks.length === 0)
+        return null;
+    return fallbacks.length > 0 ? { primary, fallbacks } : { primary };
+}
+function hasAuthForProvider(provider, cfg) {
+    const normalized = normalizeProviderId(provider);
+    if (resolveEnvApiKey(normalized))
+        return true;
+    if (getCustomProviderApiKey(cfg, normalized))
+        return true;
+    const entries = listCredentialEntriesSync();
+    return entries.some((entry) => normalizeProviderId(entry.service) === normalized);
+}
+function resolveImageModelFromConfig(cfg, provider) {
+    const providers = cfg?.models?.providers ?? {};
+    const entry = providers[provider];
+    for (const model of entry?.models ?? []) {
+        if (!model?.id)
+            continue;
+        if (Array.isArray(model.input) && model.input.includes("image")) {
+            return model.id;
+        }
+    }
+    return null;
+}
+export function resolveImageModelConfigForTool(params) {
+    void params.agentDir;
+    const explicit = normalizeImageModelConfig(params.cfg?.agent?.imageModel);
+    if (explicit)
+        return explicit;
+    const rawPrimary = typeof params.cfg?.agent?.model === "string"
+        ? params.cfg?.agent?.model
+        : params.cfg?.agent?.model?.primary;
+    if (!rawPrimary?.trim())
+        return null;
+    const parsed = parseModelRef(rawPrimary, DEFAULT_PROVIDER);
+    if (!parsed)
+        return null;
+    const provider = normalizeProviderId(parsed.provider);
+    const configImageModel = resolveImageModelFromConfig(params.cfg, provider);
+    const mapped = DEFAULT_IMAGE_MODELS[provider];
+    const primaryModelId = configImageModel ?? mapped;
+    if (!primaryModelId)
+        return null;
+    if (!hasAuthForProvider(provider, params.cfg))
+        return null;
+    const fallbacks = [];
+    for (const fallbackProvider of ["openai", "anthropic"]) {
+        if (fallbackProvider === provider)
+            continue;
+        const fallbackModelId = DEFAULT_IMAGE_MODELS[fallbackProvider];
+        if (!fallbackModelId)
+            continue;
+        if (hasAuthForProvider(fallbackProvider, params.cfg)) {
+            fallbacks.push(`${fallbackProvider}/${fallbackModelId}`);
+        }
+    }
+    return fallbacks.length > 0
+        ? { primary: `${provider}/${primaryModelId}`, fallbacks }
+        : { primary: `${provider}/${primaryModelId}` };
 }
 function pickMaxBytes(cfg, maxBytesMb) {
     if (typeof maxBytesMb === "number" &&
@@ -80,12 +154,23 @@ async function runImagePrompt(params) {
     };
 }
 export function createImageTool(options) {
-    if (!ensureImageToolConfigured(options?.config))
+    const resolvedConfig = resolveImageModelConfigForTool({
+        cfg: options?.config,
+        agentDir: options?.agentDir,
+    });
+    if (!resolvedConfig)
         return null;
     const agentDir = options?.agentDir;
     if (!agentDir?.trim()) {
         throw new Error("createImageTool requires agentDir when enabled");
     }
+    const cfgWithImageModel = (() => {
+        const cfg = options?.config ?? {};
+        const agent = cfg.agent ?? {};
+        if (normalizeImageModelConfig(agent.imageModel))
+            return cfg;
+        return { ...cfg, agent: { ...agent, imageModel: resolvedConfig } };
+    })();
     return {
         label: "Image",
         name: "image",
@@ -121,7 +206,7 @@ export function createImageTool(options) {
             const mimeType = media.contentType ?? "image/png";
             const base64 = media.buffer.toString("base64");
             const result = await runImagePrompt({
-                cfg: options?.config,
+                cfg: cfgWithImageModel,
                 agentDir,
                 modelOverride,
                 prompt: promptRaw,

package/dist/agents/tools/sessions-announce-target.js

@@ -20,7 +20,11 @@ export async function resolveAnnounceTarget(params) {
         const sessions = Array.isArray(list?.sessions) ? list.sessions : [];
         const match = sessions.find((entry) => entry?.key === params.sessionKey) ??
             sessions.find((entry) => entry?.key === params.displayKey);
-        const provider = typeof match?.lastProvider === "string" ? match.lastProvider : undefined;
+        const provider = typeof match?.lastChannel === "string"
+            ? match.lastChannel
+            : typeof match?.lastProvider === "string"
+                ? match.lastProvider
+                : undefined;
         const to = typeof match?.lastTo === "string" ? match.lastTo : undefined;
         const accountId = typeof match?.lastAccountId === "string"
             ? match.lastAccountId