@intent-systems/nexus 2026.1.5-3

package/dist/agents/subagent-registry.js

@@ -0,0 +1,321 @@
+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 { readLatestAssistantReply, runAgentStep } from "./tools/agent-step.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() : "";
+    if (!sessionKey || !parentSessionKey)
+        return null;
+    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;
+    return {
+        ...entry,
+        agentId,
+        sessionKey,
+        parentSessionKey,
+        createdAt,
+        status,
+        requesterChannel: entry.requesterChannel ?? legacyRequester,
+    };
+}
+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,
+        `Post target channel: ${params.announceChannel}.`,
+        `Original task: ${taskLine}`,
+        params.subagentReply
+            ? `Sub-agent result: ${params.subagentReply}`
+            : "Sub-agent result: (not available).",
+        "",
+        "**You MUST announce your result.** The requester is waiting for your response.",
+        "Provide a brief, useful summary of what you accomplished.",
+        'Only reply "ANNOUNCE_SKIP" if the task completely failed with no useful output.',
+        "Your reply will be posted to the requester chat.",
+    ].filter(Boolean);
+    return lines.join("\n");
+}
+function extractMessageText(message) {
+    if (!message || typeof message !== "object")
+        return undefined;
+    const content = message.content;
+    if (!Array.isArray(content))
+        return undefined;
+    const chunks = [];
+    for (const block of content) {
+        if (!block || typeof block !== "object")
+            continue;
+        if (block.type !== "text")
+            continue;
+        const text = block.text;
+        if (typeof text === "string" && text.trim()) {
+            chunks.push(text);
+        }
+    }
+    const joined = chunks.join("").trim();
+    return joined ? joined : undefined;
+}
+async function readSubagentTask(sessionKey) {
+    try {
+        const history = (await callGateway({
+            method: "chat.history",
+            params: { sessionKey, limit: 50 },
+        }));
+        const messages = stripToolMessages(Array.isArray(history?.messages) ? history.messages : []);
+        for (const message of messages) {
+            const role = message.role;
+            if (role !== "user")
+                continue;
+            const text = extractMessageText(message);
+            if (text)
+                return text;
+        }
+    }
+    catch {
+        // ignore
+    }
+    return undefined;
+}
+async function runSubagentAnnounceFlow(params) {
+    let status = "pending";
+    const timeoutMs = typeof params.timeoutMs === "number" && params.timeoutMs > 0 ? params.timeoutMs : 30_000;
+    try {
+        let reply = params.roundOneReply?.trim();
+        if (!reply) {
+            if (params.childRunId) {
+                const waitMs = Math.min(timeoutMs, 60_000);
+                const wait = (await callGateway({
+                    method: "agent.wait",
+                    params: {
+                        runId: params.childRunId,
+                        timeoutMs: waitMs,
+                    },
+                    timeoutMs: waitMs + 2000,
+                }));
+                if (wait?.status !== "ok")
+                    return "pending";
+            }
+            reply = await readLatestAssistantReply({
+                sessionKey: params.childSessionKey,
+            });
+        }
+        if (!reply || !reply.trim())
+            return "pending";
+        const announceTarget = await resolveAnnounceTarget({
+            sessionKey: params.requesterSessionKey,
+            displayKey: params.requesterDisplayKey,
+        });
+        if (!announceTarget) {
+            status = "failed";
+            return status;
+        }
+        const task = params.task?.trim() || (await readSubagentTask(params.childSessionKey));
+        const announcePrompt = buildSubagentAnnouncePrompt({
+            requesterSessionKey: params.requesterSessionKey,
+            requesterChannel: params.requesterChannel,
+            announceChannel: announceTarget.provider,
+            task,
+            subagentReply: reply,
+        });
+        const announceReply = await runAgentStep({
+            sessionKey: params.childSessionKey,
+            message: "Sub-agent announce step.",
+            extraSystemPrompt: announcePrompt,
+            timeoutMs,
+            lane: "nested",
+        });
+        if (!announceReply || !announceReply.trim() || isAnnounceSkip(announceReply)) {
+            status = "announced";
+            return status;
+        }
+        await callGateway({
+            method: "send",
+            params: {
+                to: announceTarget.to,
+                message: announceReply.trim(),
+                provider: announceTarget.provider,
+                accountId: announceTarget.accountId,
+                idempotencyKey: crypto.randomUUID(),
+            },
+            timeoutMs: 10_000,
+        });
+        status = "announced";
+        return status;
+    }
+    catch {
+        status = "failed";
+        return status;
+    }
+    finally {
+        if (params.cleanup === "delete" && status !== "pending") {
+            try {
+                await callGateway({
+                    method: "sessions.delete",
+                    params: { key: params.childSessionKey, deleteTranscript: true },
+                    timeoutMs: 10_000,
+                });
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+}
+export function createSubagentRegistry(params) {
+    const store = params?.store ?? createFileSubagentStore(params?.stateDir ?? STATE_DIR_NEXUS);
+    const entries = new Map();
+    let initialized = false;
+    let resumeInFlight = null;
+    const initializeFromStore = () => {
+        if (initialized)
+            return;
+        initialized = true;
+        const stored = store.load();
+        for (const entry of stored) {
+            const normalized = normalizeStoredEntry(entry);
+            if (normalized) {
+                entries.set(normalized.sessionKey, normalized);
+            }
+        }
+    };
+    const persistToStore = () => {
+        const list = Array.from(entries.values()).sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+        store.save(list);
+    };
+    const register = (params) => {
+        initializeFromStore();
+        const existing = entries.get(params.sessionKey);
+        const createdAt = existing?.createdAt ?? new Date().toISOString();
+        const agentId = normalizeAgentId(parseAgentSessionKey(params.sessionKey)?.agentId ??
+            parseAgentSessionKey(params.parentSessionKey)?.agentId ??
+            existing?.agentId ??
+            resolveAgentIdFromSessionKey(params.sessionKey));
+        const next = {
+            agentId,
+            sessionKey: params.sessionKey,
+            parentSessionKey: params.parentSessionKey,
+            createdAt,
+            status: "pending",
+            task: params.task ?? existing?.task,
+            requesterChannel: params.requesterChannel ?? existing?.requesterChannel,
+            runId: params.runId ?? existing?.runId,
+            cleanup: params.cleanup ?? existing?.cleanup,
+            timeoutMs: params.timeoutMs ?? existing?.timeoutMs,
+        };
+        entries.set(params.sessionKey, next);
+        persistToStore();
+        return next;
+    };
+    const update = (sessionKey, updates) => {
+        initializeFromStore();
+        const existing = entries.get(sessionKey);
+        if (!existing)
+            return undefined;
+        const next = {
+            ...existing,
+            ...updates,
+            agentId: existing.agentId,
+            sessionKey: existing.sessionKey,
+            parentSessionKey: existing.parentSessionKey,
+            createdAt: existing.createdAt,
+        };
+        entries.set(sessionKey, next);
+        persistToStore();
+        return next;
+    };
+    const markAnnounced = (sessionKey) => {
+        update(sessionKey, { status: "announced" });
+    };
+    const markFailed = (sessionKey) => {
+        update(sessionKey, { status: "failed" });
+    };
+    const get = (sessionKey) => {
+        initializeFromStore();
+        return entries.get(sessionKey);
+    };
+    const list = () => {
+        initializeFromStore();
+        return Array.from(entries.values());
+    };
+    const runAnnouncement = async (params) => {
+        const status = await runSubagentAnnounceFlow(params);
+        if (status === "announced") {
+            markAnnounced(params.childSessionKey);
+        }
+        else if (status === "failed") {
+            markFailed(params.childSessionKey);
+        }
+        return status;
+    };
+    const resumePendingAnnouncements = async () => {
+        initializeFromStore();
+        if (resumeInFlight)
+            return resumeInFlight;
+        resumeInFlight = (async () => {
+            const pending = Array.from(entries.values()).filter((entry) => entry.status === "pending");
+            if (!pending.length)
+                return;
+            const cfg = loadConfig();
+            const { mainKey, alias } = resolveMainSessionAlias(cfg);
+            for (const entry of pending) {
+                const requesterInternalKey = resolveInternalSessionKey({
+                    key: entry.parentSessionKey,
+                    alias,
+                    mainKey,
+                });
+                const requesterDisplayKey = resolveDisplaySessionKey({
+                    key: requesterInternalKey,
+                    alias,
+                    mainKey,
+                });
+                await runAnnouncement({
+                    childSessionKey: entry.sessionKey,
+                    childRunId: entry.runId,
+                    requesterSessionKey: requesterInternalKey,
+                    requesterChannel: entry.requesterChannel,
+                    requesterDisplayKey,
+                    task: entry.task,
+                    timeoutMs: entry.timeoutMs,
+                    cleanup: entry.cleanup ?? "delete",
+                });
+            }
+        })().finally(() => {
+            resumeInFlight = null;
+        });
+        return resumeInFlight;
+    };
+    const clear = () => {
+        entries.clear();
+        store.clear();
+    };
+    return {
+        register,
+        update,
+        markAnnounced,
+        markFailed,
+        get,
+        list,
+        initializeFromStore,
+        persistToStore,
+        runAnnouncement,
+        resumePendingAnnouncements,
+        clear,
+    };
+}
+export const subagentRegistry = createSubagentRegistry();

package/dist/agents/subagent-registry.store.js

@@ -0,0 +1,47 @@
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import path from "node:path";
+const STORE_FILENAME = "subagent-registry.json";
+function resolveStorePath(stateDir) {
+    return path.join(stateDir, STORE_FILENAME);
+}
+function safeParse(raw) {
+    try {
+        const data = JSON.parse(raw);
+        return Array.isArray(data) ? data : [];
+    }
+    catch {
+        return [];
+    }
+}
+export function createFileSubagentStore(stateDir) {
+    const storePath = resolveStorePath(stateDir);
+    const load = () => {
+        if (!fs.existsSync(storePath))
+            return [];
+        try {
+            const raw = fs.readFileSync(storePath, "utf-8");
+            return safeParse(raw);
+        }
+        catch {
+            return [];
+        }
+    };
+    const save = (entries) => {
+        fs.mkdirSync(path.dirname(storePath), { recursive: true });
+        fs.writeFileSync(storePath, JSON.stringify(entries, null, 2), "utf-8");
+    };
+    const clear = () => {
+        try {
+            fs.unlinkSync(storePath);
+        }
+        catch {
+            // ignore
+        }
+    };
+    return { load, save, clear };
+}
+export async function createFileSubagentStoreAsync(stateDir) {
+    await fsp.mkdir(stateDir, { recursive: true });
+    return createFileSubagentStore(stateDir);
+}

package/dist/agents/system-prompt.js

@@ -0,0 +1,179 @@
+export function buildAgentSystemPromptAppend(params) {
+    const toolSummaries = {
+        read: "Read file contents",
+        write: "Create or overwrite files",
+        edit: "Make precise edits to files",
+        grep: "Search file contents for patterns",
+        find: "Find files by glob pattern",
+        ls: "List directory contents",
+        bash: "Run shell commands",
+        process: "Manage background bash sessions",
+        whatsapp_login: "Generate and wait for WhatsApp QR login",
+        browser: "Control the dedicated Nexus browser",
+        canvas: "Present/eval/snapshot the Canvas",
+        nodes: "List/describe/notify/camera/screen on paired nodes",
+        cron: "Manage cron jobs and wake events",
+        gateway: "Restart the running Gateway process",
+        sessions_list: "List sessions with filters and last messages",
+        sessions_history: "Fetch message history for a session",
+        sessions_send: "Send a message into another session",
+        image: "Analyze an image with the configured image model",
+        discord: "Send Discord reactions/messages and manage threads/channels",
+        slack: "Send Slack messages and manage channels",
+    };
+    const toolOrder = [
+        "read",
+        "write",
+        "edit",
+        "grep",
+        "find",
+        "ls",
+        "bash",
+        "process",
+        "whatsapp_login",
+        "browser",
+        "canvas",
+        "nodes",
+        "cron",
+        "gateway",
+        "sessions_list",
+        "sessions_history",
+        "sessions_send",
+        "image",
+        "discord",
+        "slack",
+    ];
+    const normalizedTools = (params.toolNames ?? [])
+        .map((tool) => tool.trim().toLowerCase())
+        .filter(Boolean);
+    const availableTools = new Set(normalizedTools);
+    const extraTools = Array.from(new Set(normalizedTools.filter((tool) => !toolOrder.includes(tool))));
+    const enabledTools = toolOrder.filter((tool) => availableTools.has(tool));
+    const disabledTools = toolOrder.filter((tool) => !availableTools.has(tool));
+    const toolLines = enabledTools.map((tool) => {
+        const summary = toolSummaries[tool];
+        return summary ? `- ${tool}: ${summary}` : `- ${tool}`;
+    });
+    for (const tool of extraTools.sort()) {
+        toolLines.push(`- ${tool}`);
+    }
+    const thinkHint = params.defaultThinkLevel && params.defaultThinkLevel !== "off"
+        ? `Default thinking level: ${params.defaultThinkLevel}.`
+        : "Default thinking level: off.";
+    const extraSystemPrompt = params.extraSystemPrompt?.trim();
+    const ownerNumbers = (params.ownerNumbers ?? [])
+        .map((value) => value.trim())
+        .filter(Boolean);
+    const ownerLine = ownerNumbers.length > 0
+        ? `Owner numbers: ${ownerNumbers.join(", ")}. Treat messages from these numbers as the user.`
+        : undefined;
+    const reasoningHint = params.reasoningTagHint
+        ? [
+            "ALL internal reasoning MUST be inside <think>...</think>.",
+            "Do not output any analysis outside <think>.",
+            "Format every reply as <think>...</think> then <final>...</final>, with no other text.",
+            "Only the final user-visible reply may appear inside <final>.",
+            "Only text inside <final> is shown to the user; everything else is discarded and never seen by the user.",
+            "Example:",
+            "<think>Short internal reasoning.</think>",
+            "<final>Hey there! What would you like to do next?</final>",
+        ].join(" ")
+        : undefined;
+    const userTimezone = params.userTimezone?.trim();
+    const userTime = params.userTime?.trim();
+    const runtimeInfo = params.runtimeInfo;
+    const runtimeLines = [];
+    if (runtimeInfo?.host)
+        runtimeLines.push(`Host: ${runtimeInfo.host}`);
+    if (runtimeInfo?.os) {
+        const archSuffix = runtimeInfo.arch ? ` (${runtimeInfo.arch})` : "";
+        runtimeLines.push(`OS: ${runtimeInfo.os}${archSuffix}`);
+    }
+    else if (runtimeInfo?.arch) {
+        runtimeLines.push(`Arch: ${runtimeInfo.arch}`);
+    }
+    if (runtimeInfo?.node)
+        runtimeLines.push(`Node: ${runtimeInfo.node}`);
+    if (runtimeInfo?.model)
+        runtimeLines.push(`Model: ${runtimeInfo.model}`);
+    const lines = [
+        "You are a personal AI assistant running inside Nexus.",
+        "",
+        "## Tooling",
+        "Tool availability (filtered by policy):",
+        toolLines.length > 0
+            ? toolLines.join("\n")
+            : [
+                "Pi lists the standard tools above. This runtime enables:",
+                "- grep: search file contents for patterns",
+                "- find: find files by glob pattern",
+                "- ls: list directory contents",
+                "- bash: run shell commands (supports background via yieldMs/background)",
+                "- process: manage background bash sessions",
+                "- whatsapp_login: generate a WhatsApp QR code and wait for linking",
+                "- browser: control the Nexus dedicated browser",
+                "- canvas: present/eval/snapshot the Canvas",
+                "- nodes: list/describe/notify/camera/screen on paired nodes",
+                "- cron: manage cron jobs and wake events",
+                "- sessions_list: list sessions",
+                "- sessions_history: fetch session history",
+                "- sessions_send: send to another session",
+            ].join("\n"),
+        disabledTools.length > 0
+            ? `Unavailable tools (do not call): ${disabledTools.join(", ")}`
+            : "",
+        "TOOLS.md does not control tool availability; it is user guidance for how to use external tools.",
+        "",
+        "## Workspace",
+        `Your working directory is: ${params.workspaceDir}`,
+        "Treat this directory as the single global workspace for file operations unless explicitly instructed otherwise.",
+        "",
+        params.sandboxInfo?.enabled ? "## Sandbox" : "",
+        params.sandboxInfo?.enabled
+            ? [
+                "Tool execution is isolated in a Docker sandbox.",
+                "Some tools may be unavailable due to sandbox policy.",
+                params.sandboxInfo.workspaceDir
+                    ? `Sandbox workspace: ${params.sandboxInfo.workspaceDir}`
+                    : "",
+                params.sandboxInfo.browserControlUrl
+                    ? `Sandbox browser control URL: ${params.sandboxInfo.browserControlUrl}`
+                    : "",
+                params.sandboxInfo.browserNoVncUrl
+                    ? `Sandbox browser observer (noVNC): ${params.sandboxInfo.browserNoVncUrl}`
+                    : "",
+            ]
+                .filter(Boolean)
+                .join("\n")
+            : "",
+        params.sandboxInfo?.enabled ? "" : "",
+        ownerLine ? "## User Identity" : "",
+        ownerLine ?? "",
+        ownerLine ? "" : "",
+        "## Workspace Files (injected)",
+        "These user-editable files are loaded by Nexus and included below in Project Context.",
+        "",
+        "## Messaging Safety",
+        "Never send streaming/partial replies to external messaging surfaces; only final replies should be delivered there.",
+        "Nexus handles message transport automatically; respond normally and your reply will be delivered to the current chat.",
+        "",
+        userTimezone || userTime ? "## Time" : "",
+        userTimezone ? `User timezone: ${userTimezone}` : "",
+        userTime ? `Current user time: ${userTime}` : "",
+        userTimezone || userTime ? "" : "",
+        "## Reply Tags",
+        "To request a native reply/quote on supported surfaces, include one tag in your reply:",
+        "- [[reply_to_current]] replies to the triggering message.",
+        "- [[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.",
+        "",
+    ];
+    if (extraSystemPrompt) {
+        lines.push("## Group Chat Context", extraSystemPrompt, "");
+    }
+    if (reasoningHint) {
+        lines.push("## Reasoning Format", reasoningHint, "");
+    }
+    lines.push("## Heartbeats", 'If you receive a heartbeat poll (a user message containing just "HEARTBEAT"), and there is nothing that needs attention, reply exactly:', "HEARTBEAT_OK", 'Nexus treats a leading/trailing "HEARTBEAT_OK" as a heartbeat ack (and may discard it).', 'If something needs attention, do NOT include "HEARTBEAT_OK"; reply with the alert text instead.', "", "## Runtime", ...runtimeLines, thinkHint);
+    return lines.filter(Boolean).join("\n");
+}

package/dist/agents/timeout.js

@@ -0,0 +1,26 @@
+const DEFAULT_AGENT_TIMEOUT_SECONDS = 600;
+const normalizeNumber = (value) => typeof value === "number" && Number.isFinite(value)
+    ? Math.floor(value)
+    : undefined;
+export function resolveAgentTimeoutSeconds(cfg) {
+    const raw = normalizeNumber(cfg?.agent?.timeoutSeconds);
+    const seconds = raw ?? DEFAULT_AGENT_TIMEOUT_SECONDS;
+    return Math.max(seconds, 1);
+}
+export function resolveAgentTimeoutMs(opts) {
+    const minMs = Math.max(normalizeNumber(opts.minMs) ?? 1, 1);
+    const defaultMs = resolveAgentTimeoutSeconds(opts.cfg) * 1000;
+    const overrideMs = normalizeNumber(opts.overrideMs);
+    if (overrideMs !== undefined) {
+        if (overrideMs <= 0)
+            return defaultMs;
+        return Math.max(overrideMs, minMs);
+    }
+    const overrideSeconds = normalizeNumber(opts.overrideSeconds);
+    if (overrideSeconds !== undefined) {
+        if (overrideSeconds <= 0)
+            return defaultMs;
+        return Math.max(overrideSeconds * 1000, minMs);
+    }
+    return Math.max(defaultMs, minMs);
+}