@intent-systems/nexus 2026.1.5-3

package/dist/gateway/hooks-mapping.js

@@ -0,0 +1,282 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { CONFIG_PATH_NEXUS, } from "../config/config.js";
+const hookPresetMappings = {
+    gmail: [
+        {
+            id: "gmail",
+            match: { path: "gmail" },
+            action: "agent",
+            wakeMode: "now",
+            name: "Gmail",
+            sessionKey: "hook:gmail:{{messages[0].id}}",
+            messageTemplate: "New email from {{messages[0].from}}\nSubject: {{messages[0].subject}}\n{{messages[0].snippet}}\n{{messages[0].body}}",
+        },
+    ],
+};
+const transformCache = new Map();
+export function resolveHookMappings(hooks) {
+    const presets = hooks?.presets ?? [];
+    const mappings = [];
+    if (hooks?.mappings)
+        mappings.push(...hooks.mappings);
+    for (const preset of presets) {
+        const presetMappings = hookPresetMappings[preset];
+        if (presetMappings)
+            mappings.push(...presetMappings);
+    }
+    if (mappings.length === 0)
+        return [];
+    const configDir = path.dirname(CONFIG_PATH_NEXUS);
+    const transformsDir = hooks?.transformsDir
+        ? resolvePath(configDir, hooks.transformsDir)
+        : configDir;
+    return mappings.map((mapping, index) => normalizeHookMapping(mapping, index, transformsDir));
+}
+export async function applyHookMappings(mappings, ctx) {
+    if (mappings.length === 0)
+        return null;
+    for (const mapping of mappings) {
+        if (!mappingMatches(mapping, ctx))
+            continue;
+        const base = buildActionFromMapping(mapping, ctx);
+        if (!base.ok)
+            return base;
+        let override = null;
+        if (mapping.transform) {
+            const transform = await loadTransform(mapping.transform);
+            override = await transform(ctx);
+            if (override === null) {
+                return { ok: true, action: null, skipped: true };
+            }
+        }
+        if (!base.action)
+            return { ok: true, action: null, skipped: true };
+        const merged = mergeAction(base.action, override, mapping.action);
+        if (!merged.ok)
+            return merged;
+        return merged;
+    }
+    return null;
+}
+function normalizeHookMapping(mapping, index, transformsDir) {
+    const id = mapping.id?.trim() || `mapping-${index + 1}`;
+    const matchPath = normalizeMatchPath(mapping.match?.path);
+    const matchSource = mapping.match?.source?.trim();
+    const action = mapping.action ?? "agent";
+    const wakeMode = mapping.wakeMode ?? "now";
+    const transform = mapping.transform
+        ? {
+            modulePath: resolvePath(transformsDir, mapping.transform.module),
+            exportName: mapping.transform.export?.trim() || undefined,
+        }
+        : undefined;
+    return {
+        id,
+        matchPath,
+        matchSource,
+        action,
+        wakeMode,
+        name: mapping.name,
+        sessionKey: mapping.sessionKey,
+        messageTemplate: mapping.messageTemplate,
+        textTemplate: mapping.textTemplate,
+        deliver: mapping.deliver,
+        provider: mapping.provider,
+        to: mapping.to,
+        thinking: mapping.thinking,
+        timeoutSeconds: mapping.timeoutSeconds,
+        transform,
+    };
+}
+function mappingMatches(mapping, ctx) {
+    if (mapping.matchPath) {
+        if (mapping.matchPath !== normalizeMatchPath(ctx.path))
+            return false;
+    }
+    if (mapping.matchSource) {
+        const source = typeof ctx.payload.source === "string" ? ctx.payload.source : undefined;
+        if (!source || source !== mapping.matchSource)
+            return false;
+    }
+    return true;
+}
+function buildActionFromMapping(mapping, ctx) {
+    if (mapping.action === "wake") {
+        const text = renderTemplate(mapping.textTemplate ?? "", ctx);
+        return {
+            ok: true,
+            action: {
+                kind: "wake",
+                text,
+                mode: mapping.wakeMode ?? "now",
+            },
+        };
+    }
+    const message = renderTemplate(mapping.messageTemplate ?? "", ctx);
+    return {
+        ok: true,
+        action: {
+            kind: "agent",
+            message,
+            name: renderOptional(mapping.name, ctx),
+            wakeMode: mapping.wakeMode ?? "now",
+            sessionKey: renderOptional(mapping.sessionKey, ctx),
+            deliver: mapping.deliver,
+            provider: mapping.provider,
+            to: renderOptional(mapping.to, ctx),
+            thinking: renderOptional(mapping.thinking, ctx),
+            timeoutSeconds: mapping.timeoutSeconds,
+        },
+    };
+}
+function mergeAction(base, override, defaultAction) {
+    if (!override) {
+        return validateAction(base);
+    }
+    const kind = (override.kind ?? base.kind ?? defaultAction);
+    if (kind === "wake") {
+        const baseWake = base.kind === "wake" ? base : undefined;
+        const text = typeof override.text === "string"
+            ? override.text
+            : (baseWake?.text ?? "");
+        const mode = override.mode === "next-heartbeat"
+            ? "next-heartbeat"
+            : (baseWake?.mode ?? "now");
+        return validateAction({ kind: "wake", text, mode });
+    }
+    const baseAgent = base.kind === "agent" ? base : undefined;
+    const message = typeof override.message === "string"
+        ? override.message
+        : (baseAgent?.message ?? "");
+    const wakeMode = override.wakeMode === "next-heartbeat"
+        ? "next-heartbeat"
+        : (baseAgent?.wakeMode ?? "now");
+    return validateAction({
+        kind: "agent",
+        message,
+        wakeMode,
+        name: override.name ?? baseAgent?.name,
+        sessionKey: override.sessionKey ?? baseAgent?.sessionKey,
+        deliver: typeof override.deliver === "boolean"
+            ? override.deliver
+            : baseAgent?.deliver,
+        provider: override.provider ?? baseAgent?.provider,
+        to: override.to ?? baseAgent?.to,
+        thinking: override.thinking ?? baseAgent?.thinking,
+        timeoutSeconds: override.timeoutSeconds ?? baseAgent?.timeoutSeconds,
+    });
+}
+function validateAction(action) {
+    if (action.kind === "wake") {
+        if (!action.text?.trim()) {
+            return { ok: false, error: "hook mapping requires text" };
+        }
+        return { ok: true, action };
+    }
+    if (!action.message?.trim()) {
+        return { ok: false, error: "hook mapping requires message" };
+    }
+    return { ok: true, action };
+}
+async function loadTransform(transform) {
+    const cached = transformCache.get(transform.modulePath);
+    if (cached)
+        return cached;
+    const url = pathToFileURL(transform.modulePath).href;
+    const mod = (await import(url));
+    const fn = resolveTransformFn(mod, transform.exportName);
+    transformCache.set(transform.modulePath, fn);
+    return fn;
+}
+function resolveTransformFn(mod, exportName) {
+    const candidate = exportName
+        ? mod[exportName]
+        : (mod.default ?? mod.transform);
+    if (typeof candidate !== "function") {
+        throw new Error("hook transform module must export a function");
+    }
+    return candidate;
+}
+function resolvePath(baseDir, target) {
+    if (!target)
+        return baseDir;
+    if (path.isAbsolute(target))
+        return target;
+    return path.join(baseDir, target);
+}
+function normalizeMatchPath(raw) {
+    if (!raw)
+        return undefined;
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return undefined;
+    return trimmed.replace(/^\/+/, "").replace(/\/+$/, "");
+}
+function renderOptional(value, ctx) {
+    if (!value)
+        return undefined;
+    const rendered = renderTemplate(value, ctx).trim();
+    return rendered ? rendered : undefined;
+}
+function renderTemplate(template, ctx) {
+    if (!template)
+        return "";
+    return template.replace(/\{\{\s*([^}]+)\s*\}\}/g, (_, expr) => {
+        const value = resolveTemplateExpr(expr.trim(), ctx);
+        if (value === undefined || value === null)
+            return "";
+        if (typeof value === "string")
+            return value;
+        if (typeof value === "number" || typeof value === "boolean")
+            return String(value);
+        return JSON.stringify(value);
+    });
+}
+function resolveTemplateExpr(expr, ctx) {
+    if (expr === "path")
+        return ctx.path;
+    if (expr === "now")
+        return new Date().toISOString();
+    if (expr.startsWith("headers.")) {
+        return getByPath(ctx.headers, expr.slice("headers.".length));
+    }
+    if (expr.startsWith("query.")) {
+        return getByPath(Object.fromEntries(ctx.url.searchParams.entries()), expr.slice("query.".length));
+    }
+    if (expr.startsWith("payload.")) {
+        return getByPath(ctx.payload, expr.slice("payload.".length));
+    }
+    return getByPath(ctx.payload, expr);
+}
+function getByPath(input, pathExpr) {
+    if (!pathExpr)
+        return undefined;
+    const parts = [];
+    const re = /([^.[\]]+)|(\[(\d+)\])/g;
+    let match = re.exec(pathExpr);
+    while (match) {
+        if (match[1]) {
+            parts.push(match[1]);
+        }
+        else if (match[3]) {
+            parts.push(Number(match[3]));
+        }
+        match = re.exec(pathExpr);
+    }
+    let current = input;
+    for (const part of parts) {
+        if (current === null || current === undefined)
+            return undefined;
+        if (typeof part === "number") {
+            if (!Array.isArray(current))
+                return undefined;
+            current = current[part];
+            continue;
+        }
+        if (typeof current !== "object")
+            return undefined;
+        current = current[part];
+    }
+    return current;
+}

package/dist/gateway/hooks.js

@@ -0,0 +1,168 @@
+import { randomUUID } from "node:crypto";
+import { resolveHookMappings, } from "./hooks-mapping.js";
+const DEFAULT_HOOKS_PATH = "/hooks";
+const DEFAULT_HOOKS_MAX_BODY_BYTES = 256 * 1024;
+export function resolveHooksConfig(cfg) {
+    if (cfg.hooks?.enabled !== true)
+        return null;
+    const token = cfg.hooks?.token?.trim();
+    if (!token) {
+        throw new Error("hooks.enabled requires hooks.token");
+    }
+    const rawPath = cfg.hooks?.path?.trim() || DEFAULT_HOOKS_PATH;
+    const withSlash = rawPath.startsWith("/") ? rawPath : `/${rawPath}`;
+    const trimmed = withSlash.length > 1 ? withSlash.replace(/\/+$/, "") : withSlash;
+    if (trimmed === "/") {
+        throw new Error("hooks.path may not be '/'");
+    }
+    const maxBodyBytes = cfg.hooks?.maxBodyBytes && cfg.hooks.maxBodyBytes > 0
+        ? cfg.hooks.maxBodyBytes
+        : DEFAULT_HOOKS_MAX_BODY_BYTES;
+    const mappings = resolveHookMappings(cfg.hooks);
+    return {
+        basePath: trimmed,
+        token,
+        maxBodyBytes,
+        mappings,
+    };
+}
+export function extractHookToken(req, url) {
+    const auth = typeof req.headers.authorization === "string"
+        ? req.headers.authorization.trim()
+        : "";
+    if (auth.toLowerCase().startsWith("bearer ")) {
+        const token = auth.slice(7).trim();
+        if (token)
+            return token;
+    }
+    const headerToken = typeof req.headers["x-nexus-token"] === "string"
+        ? req.headers["x-nexus-token"].trim()
+        : "";
+    if (headerToken)
+        return headerToken;
+    const queryToken = url.searchParams.get("token");
+    if (queryToken)
+        return queryToken.trim();
+    return undefined;
+}
+export async function readJsonBody(req, maxBytes) {
+    return await new Promise((resolve) => {
+        let done = false;
+        let total = 0;
+        const chunks = [];
+        req.on("data", (chunk) => {
+            if (done)
+                return;
+            total += chunk.length;
+            if (total > maxBytes) {
+                done = true;
+                resolve({ ok: false, error: "payload too large" });
+                req.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on("end", () => {
+            if (done)
+                return;
+            done = true;
+            const raw = Buffer.concat(chunks).toString("utf-8").trim();
+            if (!raw) {
+                resolve({ ok: true, value: {} });
+                return;
+            }
+            try {
+                const parsed = JSON.parse(raw);
+                resolve({ ok: true, value: parsed });
+            }
+            catch (err) {
+                resolve({ ok: false, error: String(err) });
+            }
+        });
+        req.on("error", (err) => {
+            if (done)
+                return;
+            done = true;
+            resolve({ ok: false, error: String(err) });
+        });
+    });
+}
+export function normalizeHookHeaders(req) {
+    const headers = {};
+    for (const [key, value] of Object.entries(req.headers)) {
+        if (typeof value === "string") {
+            headers[key.toLowerCase()] = value;
+        }
+        else if (Array.isArray(value) && value.length > 0) {
+            headers[key.toLowerCase()] = value.join(", ");
+        }
+    }
+    return headers;
+}
+export function normalizeWakePayload(payload) {
+    const text = typeof payload.text === "string" ? payload.text.trim() : "";
+    if (!text)
+        return { ok: false, error: "text required" };
+    const mode = payload.mode === "next-heartbeat" ? "next-heartbeat" : "now";
+    return { ok: true, value: { text, mode } };
+}
+export function normalizeAgentPayload(payload, opts) {
+    const message = typeof payload.message === "string" ? payload.message.trim() : "";
+    if (!message)
+        return { ok: false, error: "message required" };
+    const nameRaw = payload.name;
+    const name = typeof nameRaw === "string" && nameRaw.trim() ? nameRaw.trim() : "Hook";
+    const wakeMode = payload.wakeMode === "next-heartbeat" ? "next-heartbeat" : "now";
+    const sessionKeyRaw = payload.sessionKey;
+    const idFactory = opts?.idFactory ?? randomUUID;
+    const sessionKey = typeof sessionKeyRaw === "string" && sessionKeyRaw.trim()
+        ? sessionKeyRaw.trim()
+        : `hook:${idFactory()}`;
+    const providerRaw = payload.provider;
+    const provider = providerRaw === "whatsapp" ||
+        providerRaw === "telegram" ||
+        providerRaw === "discord" ||
+        providerRaw === "slack" ||
+        providerRaw === "signal" ||
+        providerRaw === "imessage" ||
+        providerRaw === "last"
+        ? providerRaw
+        : providerRaw === "imsg"
+            ? "imessage"
+            : providerRaw === undefined
+                ? "last"
+                : null;
+    if (provider === null) {
+        return {
+            ok: false,
+            error: "provider must be last|whatsapp|telegram|discord|slack|signal|imessage",
+        };
+    }
+    const toRaw = payload.to;
+    const to = typeof toRaw === "string" && toRaw.trim() ? toRaw.trim() : undefined;
+    const deliver = payload.deliver === true;
+    const thinkingRaw = payload.thinking;
+    const thinking = typeof thinkingRaw === "string" && thinkingRaw.trim()
+        ? thinkingRaw.trim()
+        : undefined;
+    const timeoutRaw = payload.timeoutSeconds;
+    const timeoutSeconds = typeof timeoutRaw === "number" &&
+        Number.isFinite(timeoutRaw) &&
+        timeoutRaw > 0
+        ? Math.floor(timeoutRaw)
+        : undefined;
+    return {
+        ok: true,
+        value: {
+            message,
+            name,
+            wakeMode,
+            sessionKey,
+            deliver,
+            provider,
+            to,
+            thinking,
+            timeoutSeconds,
+        },
+    };
+}

package/dist/gateway/net.js

@@ -0,0 +1,29 @@
+import { pickPrimaryTailnetIPv4 } from "../infra/tailnet.js";
+export function isLoopbackAddress(ip) {
+    if (!ip)
+        return false;
+    if (ip === "127.0.0.1")
+        return true;
+    if (ip.startsWith("127."))
+        return true;
+    if (ip === "::1")
+        return true;
+    if (ip.startsWith("::ffff:127."))
+        return true;
+    return false;
+}
+export function resolveGatewayBindHost(bind) {
+    const mode = bind ?? "loopback";
+    if (mode === "loopback")
+        return "127.0.0.1";
+    if (mode === "lan")
+        return "0.0.0.0";
+    if (mode === "tailnet")
+        return pickPrimaryTailnetIPv4() ?? null;
+    if (mode === "auto")
+        return pickPrimaryTailnetIPv4() ?? "0.0.0.0";
+    return "127.0.0.1";
+}
+export function isLoopbackHost(host) {
+    return isLoopbackAddress(host);
+}

package/dist/gateway/protocol/index.js

@@ -0,0 +1,62 @@
+import AjvPkg from "ajv";
+import { AgentEventSchema, AgentParamsSchema, AgentWaitParamsSchema, ChatAbortParamsSchema, ChatEventSchema, ChatHistoryParamsSchema, ChatSendParamsSchema, ConfigGetParamsSchema, ConfigSchemaParamsSchema, ConfigSchemaResponseSchema, ConfigSetParamsSchema, ConnectParamsSchema, CronAddParamsSchema, CronJobSchema, CronListParamsSchema, CronRemoveParamsSchema, CronRunParamsSchema, CronRunsParamsSchema, CronStatusParamsSchema, CronUpdateParamsSchema, ErrorCodes, ErrorShapeSchema, EventFrameSchema, errorShape, GatewayFrameSchema, HelloOkSchema, ModelsListParamsSchema, NodeDescribeParamsSchema, NodeInvokeParamsSchema, NodeListParamsSchema, NodePairApproveParamsSchema, NodePairListParamsSchema, NodePairRejectParamsSchema, NodePairRequestParamsSchema, NodePairVerifyParamsSchema, NodeRenameParamsSchema, PollParamsSchema, PROTOCOL_VERSION, PresenceEntrySchema, ProtocolSchemas, ProvidersStatusParamsSchema, RequestFrameSchema, ResponseFrameSchema, SendParamsSchema, SessionsCompactParamsSchema, SessionsDeleteParamsSchema, SessionsListParamsSchema, SessionsPatchParamsSchema, SessionsResetParamsSchema, ShutdownEventSchema, SkillsInstallParamsSchema, SkillsStatusParamsSchema, SkillsUpdateParamsSchema, SnapshotSchema, StateVersionSchema, TalkModeParamsSchema, TickEventSchema, WakeParamsSchema, WebLoginStartParamsSchema, WebLoginWaitParamsSchema, WizardCancelParamsSchema, WizardNextParamsSchema, WizardNextResultSchema, WizardStartParamsSchema, WizardStartResultSchema, WizardStatusParamsSchema, WizardStatusResultSchema, WizardStepSchema, } from "./schema.js";
+const ajv = new AjvPkg({
+    allErrors: true,
+    strict: false,
+    removeAdditional: false,
+});
+export const validateConnectParams = ajv.compile(ConnectParamsSchema);
+export const validateRequestFrame = ajv.compile(RequestFrameSchema);
+export const validateResponseFrame = ajv.compile(ResponseFrameSchema);
+export const validateEventFrame = ajv.compile(EventFrameSchema);
+export const validateSendParams = ajv.compile(SendParamsSchema);
+export const validatePollParams = ajv.compile(PollParamsSchema);
+export const validateAgentParams = ajv.compile(AgentParamsSchema);
+export const validateAgentWaitParams = ajv.compile(AgentWaitParamsSchema);
+export const validateWakeParams = ajv.compile(WakeParamsSchema);
+export const validateNodePairRequestParams = ajv.compile(NodePairRequestParamsSchema);
+export const validateNodePairListParams = ajv.compile(NodePairListParamsSchema);
+export const validateNodePairApproveParams = ajv.compile(NodePairApproveParamsSchema);
+export const validateNodePairRejectParams = ajv.compile(NodePairRejectParamsSchema);
+export const validateNodePairVerifyParams = ajv.compile(NodePairVerifyParamsSchema);
+export const validateNodeRenameParams = ajv.compile(NodeRenameParamsSchema);
+export const validateNodeListParams = ajv.compile(NodeListParamsSchema);
+export const validateNodeDescribeParams = ajv.compile(NodeDescribeParamsSchema);
+export const validateNodeInvokeParams = ajv.compile(NodeInvokeParamsSchema);
+export const validateSessionsListParams = ajv.compile(SessionsListParamsSchema);
+export const validateSessionsPatchParams = ajv.compile(SessionsPatchParamsSchema);
+export const validateSessionsResetParams = ajv.compile(SessionsResetParamsSchema);
+export const validateSessionsDeleteParams = ajv.compile(SessionsDeleteParamsSchema);
+export const validateSessionsCompactParams = ajv.compile(SessionsCompactParamsSchema);
+export const validateConfigGetParams = ajv.compile(ConfigGetParamsSchema);
+export const validateConfigSetParams = ajv.compile(ConfigSetParamsSchema);
+export const validateConfigSchemaParams = ajv.compile(ConfigSchemaParamsSchema);
+export const validateWizardStartParams = ajv.compile(WizardStartParamsSchema);
+export const validateWizardNextParams = ajv.compile(WizardNextParamsSchema);
+export const validateWizardCancelParams = ajv.compile(WizardCancelParamsSchema);
+export const validateWizardStatusParams = ajv.compile(WizardStatusParamsSchema);
+export const validateTalkModeParams = ajv.compile(TalkModeParamsSchema);
+export const validateProvidersStatusParams = ajv.compile(ProvidersStatusParamsSchema);
+export const validateModelsListParams = ajv.compile(ModelsListParamsSchema);
+export const validateSkillsStatusParams = ajv.compile(SkillsStatusParamsSchema);
+export const validateSkillsInstallParams = ajv.compile(SkillsInstallParamsSchema);
+export const validateSkillsUpdateParams = ajv.compile(SkillsUpdateParamsSchema);
+export const validateCronListParams = ajv.compile(CronListParamsSchema);
+export const validateCronStatusParams = ajv.compile(CronStatusParamsSchema);
+export const validateCronAddParams = ajv.compile(CronAddParamsSchema);
+export const validateCronUpdateParams = ajv.compile(CronUpdateParamsSchema);
+export const validateCronRemoveParams = ajv.compile(CronRemoveParamsSchema);
+export const validateCronRunParams = ajv.compile(CronRunParamsSchema);
+export const validateCronRunsParams = ajv.compile(CronRunsParamsSchema);
+export const validateChatHistoryParams = ajv.compile(ChatHistoryParamsSchema);
+export const validateChatSendParams = ajv.compile(ChatSendParamsSchema);
+export const validateChatAbortParams = ajv.compile(ChatAbortParamsSchema);
+export const validateChatEvent = ajv.compile(ChatEventSchema);
+export const validateWebLoginStartParams = ajv.compile(WebLoginStartParamsSchema);
+export const validateWebLoginWaitParams = ajv.compile(WebLoginWaitParamsSchema);
+export function formatValidationErrors(errors) {
+    if (!errors)
+        return "unknown validation error";
+    return ajv.errorsText(errors, { separator: "; " });
+}
+export { ConnectParamsSchema, HelloOkSchema, RequestFrameSchema, ResponseFrameSchema, EventFrameSchema, GatewayFrameSchema, PresenceEntrySchema, SnapshotSchema, ErrorShapeSchema, StateVersionSchema, AgentEventSchema, ChatEventSchema, SendParamsSchema, PollParamsSchema, AgentParamsSchema, WakeParamsSchema, NodePairRequestParamsSchema, NodePairListParamsSchema, NodePairApproveParamsSchema, NodePairRejectParamsSchema, NodePairVerifyParamsSchema, NodeListParamsSchema, NodeInvokeParamsSchema, SessionsListParamsSchema, SessionsPatchParamsSchema, SessionsResetParamsSchema, SessionsDeleteParamsSchema, SessionsCompactParamsSchema, ConfigGetParamsSchema, ConfigSetParamsSchema, ConfigSchemaParamsSchema, ConfigSchemaResponseSchema, WizardStartParamsSchema, WizardNextParamsSchema, WizardCancelParamsSchema, WizardStatusParamsSchema, WizardStepSchema, WizardNextResultSchema, WizardStartResultSchema, WizardStatusResultSchema, ProvidersStatusParamsSchema, WebLoginStartParamsSchema, WebLoginWaitParamsSchema, ModelsListParamsSchema, SkillsStatusParamsSchema, SkillsInstallParamsSchema, SkillsUpdateParamsSchema, CronJobSchema, CronListParamsSchema, CronStatusParamsSchema, CronAddParamsSchema, CronUpdateParamsSchema, CronRemoveParamsSchema, CronRunParamsSchema, CronRunsParamsSchema, ChatHistoryParamsSchema, ChatSendParamsSchema, TickEventSchema, ShutdownEventSchema, ProtocolSchemas, PROTOCOL_VERSION, ErrorCodes, errorShape, };