@intent-systems/nexus 2026.1.5-3

package/dist/hooks/gmail-watcher.js

@@ -0,0 +1,190 @@
+/**
+ * Gmail Watcher Service
+ *
+ * Automatically starts `gog gmail watch serve` when the gateway starts,
+ * if hooks.gmail is configured with an account.
+ */
+import { spawn } from "node:child_process";
+import { hasBinary } from "../agents/skills.js";
+import { createSubsystemLogger } from "../logging.js";
+import { runCommandWithTimeout } from "../process/exec.js";
+import { buildGogWatchServeArgs, buildGogWatchStartArgs, resolveGmailHookRuntimeConfig, } from "./gmail.js";
+import { ensureTailscaleEndpoint } from "./gmail-setup-utils.js";
+const log = createSubsystemLogger("gmail-watcher");
+const ADDRESS_IN_USE_RE = /address already in use|EADDRINUSE/i;
+export function isAddressInUseError(line) {
+    return ADDRESS_IN_USE_RE.test(line);
+}
+let watcherProcess = null;
+let renewInterval = null;
+let shuttingDown = false;
+let currentConfig = null;
+/**
+ * Check if gog binary is available
+ */
+function isGogAvailable() {
+    return hasBinary("gog");
+}
+/**
+ * Start the Gmail watch (registers with Gmail API)
+ */
+async function startGmailWatch(cfg) {
+    const args = ["gog", ...buildGogWatchStartArgs(cfg)];
+    try {
+        const result = await runCommandWithTimeout(args, { timeoutMs: 120_000 });
+        if (result.code !== 0) {
+            const message = result.stderr || result.stdout || "gog watch start failed";
+            log.error(`watch start failed: ${message}`);
+            return false;
+        }
+        log.info(`watch started for ${cfg.account}`);
+        return true;
+    }
+    catch (err) {
+        log.error(`watch start error: ${String(err)}`);
+        return false;
+    }
+}
+/**
+ * Spawn the gog gmail watch serve process
+ */
+function spawnGogServe(cfg) {
+    const args = buildGogWatchServeArgs(cfg);
+    log.info(`starting gog ${args.join(" ")}`);
+    let addressInUse = false;
+    const child = spawn("gog", args, {
+        stdio: ["ignore", "pipe", "pipe"],
+        detached: false,
+    });
+    child.stdout?.on("data", (data) => {
+        const line = data.toString().trim();
+        if (line)
+            log.info(`[gog] ${line}`);
+    });
+    child.stderr?.on("data", (data) => {
+        const line = data.toString().trim();
+        if (!line)
+            return;
+        if (isAddressInUseError(line)) {
+            addressInUse = true;
+        }
+        log.warn(`[gog] ${line}`);
+    });
+    child.on("error", (err) => {
+        log.error(`gog process error: ${String(err)}`);
+    });
+    child.on("exit", (code, signal) => {
+        if (shuttingDown)
+            return;
+        if (addressInUse) {
+            log.warn("gog serve failed to bind (address already in use); stopping restarts. " +
+                "Another watcher is likely running. Set NEXUS_SKIP_GMAIL_WATCHER=1 or stop the other process.");
+            watcherProcess = null;
+            return;
+        }
+        log.warn(`gog exited (code=${code}, signal=${signal}); restarting in 5s`);
+        watcherProcess = null;
+        setTimeout(() => {
+            if (shuttingDown || !currentConfig)
+                return;
+            watcherProcess = spawnGogServe(currentConfig);
+        }, 5000);
+    });
+    return child;
+}
+/**
+ * Start the Gmail watcher service.
+ * Called automatically by the gateway if hooks.gmail is configured.
+ */
+export async function startGmailWatcher(cfg) {
+    // Check if gmail hooks are configured
+    if (!cfg.hooks?.enabled) {
+        return { started: false, reason: "hooks not enabled" };
+    }
+    if (!cfg.hooks?.gmail?.account) {
+        return { started: false, reason: "no gmail account configured" };
+    }
+    // Check if gog is available
+    const gogAvailable = isGogAvailable();
+    if (!gogAvailable) {
+        return { started: false, reason: "gog binary not found" };
+    }
+    // Resolve the full runtime config
+    const resolved = resolveGmailHookRuntimeConfig(cfg, {});
+    if (!resolved.ok) {
+        return { started: false, reason: resolved.error };
+    }
+    const runtimeConfig = resolved.value;
+    currentConfig = runtimeConfig;
+    // Set up Tailscale endpoint if needed
+    if (runtimeConfig.tailscale.mode !== "off") {
+        try {
+            await ensureTailscaleEndpoint({
+                mode: runtimeConfig.tailscale.mode,
+                path: runtimeConfig.tailscale.path,
+                port: runtimeConfig.serve.port,
+            });
+            log.info(`tailscale ${runtimeConfig.tailscale.mode} configured for port ${runtimeConfig.serve.port}`);
+        }
+        catch (err) {
+            log.error(`tailscale setup failed: ${String(err)}`);
+            return {
+                started: false,
+                reason: `tailscale setup failed: ${String(err)}`,
+            };
+        }
+    }
+    // Start the Gmail watch (register with Gmail API)
+    const watchStarted = await startGmailWatch(runtimeConfig);
+    if (!watchStarted) {
+        log.warn("gmail watch start failed, but continuing with serve");
+    }
+    // Spawn the gog serve process
+    shuttingDown = false;
+    watcherProcess = spawnGogServe(runtimeConfig);
+    // Set up renewal interval
+    const renewMs = runtimeConfig.renewEveryMinutes * 60_000;
+    renewInterval = setInterval(() => {
+        if (shuttingDown)
+            return;
+        void startGmailWatch(runtimeConfig);
+    }, renewMs);
+    log.info(`gmail watcher started for ${runtimeConfig.account} (renew every ${runtimeConfig.renewEveryMinutes}m)`);
+    return { started: true };
+}
+/**
+ * Stop the Gmail watcher service.
+ */
+export async function stopGmailWatcher() {
+    shuttingDown = true;
+    if (renewInterval) {
+        clearInterval(renewInterval);
+        renewInterval = null;
+    }
+    if (watcherProcess) {
+        log.info("stopping gmail watcher");
+        watcherProcess.kill("SIGTERM");
+        // Wait a bit for graceful shutdown
+        await new Promise((resolve) => {
+            const timeout = setTimeout(() => {
+                if (watcherProcess) {
+                    watcherProcess.kill("SIGKILL");
+                }
+                resolve();
+            }, 3000);
+            watcherProcess?.on("exit", () => {
+                clearTimeout(timeout);
+                resolve();
+            });
+        });
+        watcherProcess = null;
+    }
+    currentConfig = null;
+    log.info("gmail watcher stopped");
+}
+/**
+ * Check if the Gmail watcher is running.
+ */
+export function isGmailWatcherRunning() {
+    return watcherProcess !== null && !shuttingDown;
+}

package/dist/hooks/gmail.js

@@ -0,0 +1,177 @@
+import { randomBytes } from "node:crypto";
+import { DEFAULT_GATEWAY_PORT, resolveGatewayPort, } from "../config/config.js";
+export const DEFAULT_GMAIL_LABEL = "INBOX";
+export const DEFAULT_GMAIL_TOPIC = "gog-gmail-watch";
+export const DEFAULT_GMAIL_SUBSCRIPTION = "gog-gmail-watch-push";
+export const DEFAULT_GMAIL_SERVE_BIND = "127.0.0.1";
+export const DEFAULT_GMAIL_SERVE_PORT = 8788;
+export const DEFAULT_GMAIL_SERVE_PATH = "/gmail-pubsub";
+export const DEFAULT_GMAIL_MAX_BYTES = 20_000;
+export const DEFAULT_GMAIL_RENEW_MINUTES = 12 * 60;
+export const DEFAULT_HOOKS_PATH = "/hooks";
+export function generateHookToken(bytes = 24) {
+    return randomBytes(bytes).toString("hex");
+}
+export function mergeHookPresets(existing, preset) {
+    const next = new Set((existing ?? []).map((item) => item.trim()).filter(Boolean));
+    next.add(preset);
+    return Array.from(next);
+}
+export function normalizeHooksPath(raw) {
+    const base = raw?.trim() || DEFAULT_HOOKS_PATH;
+    if (base === "/")
+        return DEFAULT_HOOKS_PATH;
+    const withSlash = base.startsWith("/") ? base : `/${base}`;
+    return withSlash.replace(/\/+$/, "");
+}
+export function normalizeServePath(raw) {
+    const base = raw?.trim() || DEFAULT_GMAIL_SERVE_PATH;
+    // Tailscale funnel/serve strips the set-path prefix before proxying.
+    // To accept requests at /<path> externally, gog must listen on "/".
+    if (base === "/")
+        return "/";
+    const withSlash = base.startsWith("/") ? base : `/${base}`;
+    return withSlash.replace(/\/+$/, "");
+}
+export function buildDefaultHookUrl(hooksPath, port = DEFAULT_GATEWAY_PORT) {
+    const basePath = normalizeHooksPath(hooksPath);
+    const baseUrl = `http://127.0.0.1:${port}`;
+    return joinUrl(baseUrl, `${basePath}/gmail`);
+}
+export function resolveGmailHookRuntimeConfig(cfg, overrides) {
+    const hooks = cfg.hooks;
+    const gmail = hooks?.gmail;
+    const hookToken = overrides.hookToken ?? hooks?.token ?? "";
+    if (!hookToken) {
+        return { ok: false, error: "hooks.token missing (needed for gmail hook)" };
+    }
+    const account = overrides.account ?? gmail?.account ?? "";
+    if (!account) {
+        return { ok: false, error: "gmail account required" };
+    }
+    const topic = overrides.topic ?? gmail?.topic ?? "";
+    if (!topic) {
+        return { ok: false, error: "gmail topic required" };
+    }
+    const subscription = overrides.subscription ?? gmail?.subscription ?? DEFAULT_GMAIL_SUBSCRIPTION;
+    const pushToken = overrides.pushToken ?? gmail?.pushToken ?? "";
+    if (!pushToken) {
+        return { ok: false, error: "gmail push token required" };
+    }
+    const hookUrl = overrides.hookUrl ??
+        gmail?.hookUrl ??
+        buildDefaultHookUrl(hooks?.path, resolveGatewayPort(cfg));
+    const includeBody = overrides.includeBody ?? gmail?.includeBody ?? true;
+    const maxBytesRaw = overrides.maxBytes ?? gmail?.maxBytes;
+    const maxBytes = typeof maxBytesRaw === "number" &&
+        Number.isFinite(maxBytesRaw) &&
+        maxBytesRaw > 0
+        ? Math.floor(maxBytesRaw)
+        : DEFAULT_GMAIL_MAX_BYTES;
+    const renewEveryMinutesRaw = overrides.renewEveryMinutes ?? gmail?.renewEveryMinutes;
+    const renewEveryMinutes = typeof renewEveryMinutesRaw === "number" &&
+        Number.isFinite(renewEveryMinutesRaw) &&
+        renewEveryMinutesRaw > 0
+        ? Math.floor(renewEveryMinutesRaw)
+        : DEFAULT_GMAIL_RENEW_MINUTES;
+    const serveBind = overrides.serveBind ?? gmail?.serve?.bind ?? DEFAULT_GMAIL_SERVE_BIND;
+    const servePortRaw = overrides.servePort ?? gmail?.serve?.port;
+    const servePort = typeof servePortRaw === "number" &&
+        Number.isFinite(servePortRaw) &&
+        servePortRaw > 0
+        ? Math.floor(servePortRaw)
+        : DEFAULT_GMAIL_SERVE_PORT;
+    const servePathRaw = overrides.servePath ?? gmail?.serve?.path;
+    const hasExplicitServePath = typeof servePathRaw === "string" && servePathRaw.trim().length > 0;
+    const tailscaleMode = overrides.tailscaleMode ?? gmail?.tailscale?.mode ?? "off";
+    // When exposing the push endpoint via Tailscale, the public path is stripped
+    // before proxying; use "/" internally unless the user set a path explicitly.
+    const servePath = normalizeServePath(tailscaleMode !== "off" && !hasExplicitServePath ? "/" : servePathRaw);
+    const tailscalePathRaw = overrides.tailscalePath ?? gmail?.tailscale?.path;
+    const tailscalePath = normalizeServePath(tailscaleMode !== "off" && !tailscalePathRaw
+        ? hasExplicitServePath
+            ? servePathRaw
+            : DEFAULT_GMAIL_SERVE_PATH
+        : (tailscalePathRaw ?? servePath));
+    return {
+        ok: true,
+        value: {
+            account,
+            label: overrides.label ?? gmail?.label ?? DEFAULT_GMAIL_LABEL,
+            topic,
+            subscription,
+            pushToken,
+            hookToken,
+            hookUrl,
+            includeBody,
+            maxBytes,
+            renewEveryMinutes,
+            serve: {
+                bind: serveBind,
+                port: servePort,
+                path: servePath,
+            },
+            tailscale: {
+                mode: tailscaleMode,
+                path: tailscalePath,
+            },
+        },
+    };
+}
+export function buildGogWatchStartArgs(cfg) {
+    return [
+        "gmail",
+        "watch",
+        "start",
+        "--account",
+        cfg.account,
+        "--label",
+        cfg.label,
+        "--topic",
+        cfg.topic,
+    ];
+}
+export function buildGogWatchServeArgs(cfg) {
+    const args = [
+        "gmail",
+        "watch",
+        "serve",
+        "--account",
+        cfg.account,
+        "--bind",
+        cfg.serve.bind,
+        "--port",
+        String(cfg.serve.port),
+        "--path",
+        cfg.serve.path,
+        "--token",
+        cfg.pushToken,
+        "--hook-url",
+        cfg.hookUrl,
+        "--hook-token",
+        cfg.hookToken,
+    ];
+    if (cfg.includeBody) {
+        args.push("--include-body");
+    }
+    if (cfg.maxBytes > 0) {
+        args.push("--max-bytes", String(cfg.maxBytes));
+    }
+    return args;
+}
+export function buildTopicPath(projectId, topicName) {
+    return `projects/${projectId}/topics/${topicName}`;
+}
+export function parseTopicPath(topic) {
+    const match = topic.trim().match(/^projects\/([^/]+)\/topics\/([^/]+)$/i);
+    if (!match)
+        return null;
+    return { projectId: match[1] ?? "", topicName: match[2] ?? "" };
+}
+function joinUrl(base, path) {
+    const url = new URL(base);
+    const basePath = url.pathname.replace(/\/+$/, "");
+    const extra = path.startsWith("/") ? path : `/${path}`;
+    url.pathname = `${basePath}${extra}`;
+    return url.toString();
+}

package/dist/imessage/client.js

@@ -0,0 +1,165 @@
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import { resolveUserPath } from "../utils.js";
+export class IMessageRpcClient {
+    cliPath;
+    dbPath;
+    runtime;
+    onNotification;
+    pending = new Map();
+    closed;
+    closedResolve = null;
+    child = null;
+    reader = null;
+    nextId = 1;
+    constructor(opts = {}) {
+        this.cliPath = opts.cliPath?.trim() || "imsg";
+        this.dbPath = opts.dbPath?.trim()
+            ? resolveUserPath(opts.dbPath)
+            : undefined;
+        this.runtime = opts.runtime;
+        this.onNotification = opts.onNotification;
+        this.closed = new Promise((resolve) => {
+            this.closedResolve = resolve;
+        });
+    }
+    async start() {
+        if (this.child)
+            return;
+        const args = ["rpc"];
+        if (this.dbPath) {
+            args.push("--db", this.dbPath);
+        }
+        const child = spawn(this.cliPath, args, {
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        this.child = child;
+        this.reader = createInterface({ input: child.stdout });
+        this.reader.on("line", (line) => {
+            const trimmed = line.trim();
+            if (!trimmed)
+                return;
+            this.handleLine(trimmed);
+        });
+        child.stderr?.on("data", (chunk) => {
+            const lines = chunk.toString().split(/\r?\n/);
+            for (const line of lines) {
+                if (!line.trim())
+                    continue;
+                this.runtime?.error?.(`imsg rpc: ${line.trim()}`);
+            }
+        });
+        child.on("error", (err) => {
+            this.failAll(err instanceof Error ? err : new Error(String(err)));
+            this.closedResolve?.();
+        });
+        child.on("close", (code, signal) => {
+            if (code !== 0 && code !== null) {
+                const reason = signal ? `signal ${signal}` : `code ${code}`;
+                this.failAll(new Error(`imsg rpc exited (${reason})`));
+            }
+            else {
+                this.failAll(new Error("imsg rpc closed"));
+            }
+            this.closedResolve?.();
+        });
+    }
+    async stop() {
+        if (!this.child)
+            return;
+        this.reader?.close();
+        this.reader = null;
+        this.child.stdin?.end();
+        const child = this.child;
+        this.child = null;
+        await Promise.race([
+            this.closed,
+            new Promise((resolve) => {
+                setTimeout(() => {
+                    if (!child.killed)
+                        child.kill("SIGTERM");
+                    resolve();
+                }, 500);
+            }),
+        ]);
+    }
+    async waitForClose() {
+        await this.closed;
+    }
+    async request(method, params, opts) {
+        if (!this.child || !this.child.stdin) {
+            throw new Error("imsg rpc not running");
+        }
+        const id = this.nextId++;
+        const payload = {
+            jsonrpc: "2.0",
+            id,
+            method,
+            params: params ?? {},
+        };
+        const line = `${JSON.stringify(payload)}\n`;
+        const timeoutMs = opts?.timeoutMs ?? 10_000;
+        const response = new Promise((resolve, reject) => {
+            const key = String(id);
+            const timer = timeoutMs > 0
+                ? setTimeout(() => {
+                    this.pending.delete(key);
+                    reject(new Error(`imsg rpc timeout (${method})`));
+                }, timeoutMs)
+                : undefined;
+            this.pending.set(key, {
+                resolve: (value) => resolve(value),
+                reject,
+                timer,
+            });
+        });
+        this.child.stdin.write(line);
+        return await response;
+    }
+    handleLine(line) {
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch (err) {
+            const detail = err instanceof Error ? err.message : String(err);
+            this.runtime?.error?.(`imsg rpc: failed to parse ${line}: ${detail}`);
+            return;
+        }
+        if (parsed.id !== undefined && parsed.id !== null) {
+            const key = String(parsed.id);
+            const pending = this.pending.get(key);
+            if (!pending)
+                return;
+            if (pending.timer)
+                clearTimeout(pending.timer);
+            this.pending.delete(key);
+            if (parsed.error) {
+                const msg = parsed.error.message ?? "imsg rpc error";
+                pending.reject(new Error(msg));
+                return;
+            }
+            pending.resolve(parsed.result);
+            return;
+        }
+        if (parsed.method) {
+            this.onNotification?.({
+                method: parsed.method,
+                params: parsed.params,
+            });
+        }
+    }
+    failAll(err) {
+        for (const [key, pending] of this.pending.entries()) {
+            if (pending.timer)
+                clearTimeout(pending.timer);
+            pending.reject(err);
+            this.pending.delete(key);
+        }
+    }
+}
+export async function createIMessageRpcClient(opts = {}) {
+    const client = new IMessageRpcClient(opts);
+    await client.start();
+    return client;
+}

package/dist/imessage/index.js

@@ -0,0 +1,3 @@
+export { monitorIMessageProvider } from "./monitor.js";
+export { probeIMessage } from "./probe.js";
+export { sendMessageIMessage } from "./send.js";